Financial App Technical Writer – Adaptable Tools

SCADA Technical Writer
 

Adaptable Blotter is an app designed for use in the financial industry. It allows traders and other financial specialists to control data shown in 'grids', and it is compatible with grids from different manufacturers. My mission was to create documentation for the app, using Paligo as the authoring tool and then outputting the content as HTML5 help and as Zendesk articles.

The audience for this content are well-educated, but not necessarily IT-literate. So the key aim was to provide task-orientated content that is easy to understand, stripped of unnecessary computer jargon, but at the same time, not patronising to the users.

Read the case study or go straight to the feedback, it's up to you.

Challenges

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.

Financial software technical writer - Paligo
Financial software technical writer - Paligo

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.