Financial App Technical Writer – Adaptable Tools
The Adaptable Blotter project offered several challenges and opportunities:
- New international client who is a friend of an existing client
- First time using Paligo as an authoring tool
- First time working on financial software.
The client did have some concerns about my lack of experience in the finance industry, but I put those to rest in a brief Skype chat. Although I hadn't worked in the financial industry, I had documented software systems, many of which had the data querying features that Adaptable Blotter provides.
Prior to starting the work, I spent a couple of days working with Paligo's features to make sure I understood how it works. I quickly grasped the main concepts as they are similar to DITA and other tools like Flare. And I knew Paligo's excellent support would help if needed.
Paligo HTML5 Help and Zendesk Output
Getting to grips with Paligo proved to be easier than expected, and within 2 days, I had a clear plan for content reuse and was producing a steady stream of topics and informal topics. The only real issues that came up along the way were to do with nesting the content. There was some debate about whether topics that need to contain sub-headings should be a single topic with a bridgehead or two separate topics nested in a hierarchy. With nesting, the child-topic would appear as a sub-section in the parent article when the content is exported to Zendesk. The bridgehead had the same result, but it introduced some less than elegant auto-wording in the cross-reference to the sub-heading and it also meant the sub-section was not as available for content reuse in the future. I opted for the two topic approach, as this seemed to be the most future-proof.
Exporting to Zendesk was a simple process and just required a second publication, with the content organised specifically for the conversion to articles.
The HTML5 output was also straight-forward, and I made the HTML5 help you can see here with just a few minor changes to the default CSS.
One thing that did cause a little problem was the built-in 'Additional Links' feature that appears at the end of top-level topics (you can see it in the screen shot above). I wanted to remove this, and Paligo kindly made a customisation that allowed it to be hidden. To do this, the section element for the top-level topic had to have its Role attribute set to nosectionlink. In the CSS, the nosection link class had to be set to display:none.
The end result is a stylish, responsive HTML5 help output. I like how the default template has an accordion menu on the left-hand side, as this 'traditional' layout is not provided by some authoring tools, and yet it is a very common requirement.
Feedback from Adaptable Tools
Jonathan Wolfson, CEO, Adaptable Tools
Craig did a really great job as the technical writer for the Adaptable Blotter. Our product sits in a very niche space in the financial services industry and is difficult for those not well-experienced in the industry to understand. But Craig succeeded in understanding what the product does very quickly. And more importantly he was able to cut through the jargon and focus on the essential and key elements in the system. He asked lots of intelligent questions which not only made the Help docs more readable and useful but actually fed back into the product itself - there is no doubt that the Adaptable Blotter is more user-friendly and intuitive as a result of Craig’s consultancy efforts. We highly recommend him.