Topic-based writing: tripane or top-nav for documenting software
One of the topics that I am currently interested in is topic-based writing. My company has just adapted MadCap Flare as the main authoring tool, and we have chosen top-nav paradigm as the deliverable hosted on the password-protected website.
During our last mentoring meeting, David and I attempted to discuss the whole notion of topic-based writing, starting with a small discussion around the purpose of writing and the type of audience to consider.
David believes, and I agree with him, that the layout of the output as well as writing approach doesn’t solely depend on the latest writing fashion or your preference, you need to consider your target audience, and what you want to document.
Is your audience used to printed manuals? Are these end users, or engineers which will probably depend on a good search functionality rather than structured content?
What do you want to document? Is it software per se: how it looks like, and how to navigate within the UI, or do you want to describe the tasks you can perform using the software as the tool?
Tasks are easier to describe with top-nav, each task being a separate searchable topic. However, I find it challenging to describe UI using topic-based approach. This is why for the UI parts, I create one topic that serves as an introduction to the UI, and lists all main parts/sections of the software, providing links to the relevant topics describing them in more details. That way, I am sure that all topics are easy to find, as you can either search for them using the built-in search field, or view the list of software sections and choose the one you are interested in.
Pros and Cons of Tripane
Tripane is considered old-fashioned. However, it may be a good transitioning media for the audience that is used to printed output; it has a TOC pane that organises the content. That way the reader is always aware of where they are and how they got there. It imposes clear structure and does not include any distracting fancy design that sometimes gets in a way of obtaining information you are after. It depends on the tool used to create the tripane, but most of them have pretty decent search optimisation functionality, so it is easy to forage for information, if the reader doesn’t want to go through more traditional approach, i.e. reading the TOC.
Top-nav imposes a real web experience – the reader is usually supposed to make search against the information they want to obtain; it puts the reader right in the middle of the content, and by doing so also out of context, making it is easy to get lost. A reader needs to be a proficient web user to know how to forage for information within the top-nav system. Thy need to know how to make search in the most effective way to be able to extract exactly what they came for. One way to cater for this is to write a meta topic on how to search for information, so even the most inexperienced readers can learn how to do it effectively. It is also very important to provide additional introductory information, to minimise the feeling of being lost. I find this the most challenging part of topic-based writing, as you need to very precise and clear using as little words as possible, making sure the reader won’t skip this part.
Every writing style has its pros and cons. The most important thing to keep in mind is to know your audience expectations, and if you as a writer don’t have this luxury, cater for many different scenarios using the tools you were given. I think, my documentation team is on the good path, trying to cater for people accustomed to traditional top-down writing approach that incorporates TOCs, and people who come to the website just to search for one particular piece of information, and don’t want to waste time on looking through indexes or navigation tips. Having said that, I do recognise the long path before us to learn how to use metadata more proficient to get the best of each approach.