The Path to Killer Help Documentation: Our Journey
I began my Realisable adventure 20 months ago when James keenly saw the chance to utilise my scientific background and “fresh eyes” to analyse the help documentation for IMan. Flaws in the original documentation needed attention as they led to missed sales, frustrated users, and all too many paltry support tickets. The logic for dragging me into it was that someone who has little tech experience would be similar to one of our clients trying to access the help and use the software. If it makes sense to me, there’s a better chance that it’ll make sense to our users; if our clients have an easier time learning to use our software, it will mean that our developers can spend less time answering support queries and more time creating better data solutions, answering more complex problems and ultimately improving our service.
Along with analysing the content of the help, there was also the question of format. James wanted to somehow convert the documents from the impenetrable PDF to an accessible, online, searchable resource. Our solution was to use a market-leading one-source publishing platform called MadCap Flare. It was with this product that I spent months of my life, learning HTML and CSS, and eventually converting our key user guides into the form that they are today.
On my first review of the user guide, my most common annotation was “Why?”. In response to almost every one of these, James told me to go and try it; whatever ‘it’ was. With an internal sigh, I went off to struggle with setting up email report groups, creating XML files,translating fields, understanding what an ‘expando’ field was, and to tackle my nemesis: hierarchical data keys. I got completely lost in the software; the reason I got lost was primarily down to confusion while interpreting techie explanations & instructions (or lack thereof!). It was hard work, but I now have a thorough understanding of the software, and have successfully created documentation that makes sense to me, which will hopefully help others avoid the struggle I went through.
Since I was simultaneously learning how to use the software, we were also finding bugs that had snuck through product testing! From the beginning, James saw the opportunity for a front-to-back software development approach, and his method clearly pays off, as my review process also analyses the software itself. I’ve thoroughly reviewed the basic functionality of the software; as a result bugs that were previously missed have been discovered, and we find increasingly more ways in which the whole package can be improved. Some bugs were easily fixed, but other adjustments are a part of the next version release of IMan and will result in an even stronger product!
The online help has been live since July 2015, and I continue to refine it.