Does talking less always mean a person is shy or introvert? Or, does it simply mean that the person does not share more than needed? Now, the same line, which parts being shy and being careful, is drawn “as is” between “talking” more and “telling” more. The line – the mark of distinction – is thin, and difficult to draw. As technical writers, we perform a very difficult task – of scripting documents, despite all sorts of problems. But, more difficult it is to cut the “original script” into a lighter, edited, crispy, or sensible version (and all other positive adjectives one can think of). So, for us, carving-out that document is a skill, developing which requires learning and practicing the basics of minimalism.
Minimalism is reducing complexity and volume of content in any document. In this post, I will briefly discuss about the basics of implementing it into user documentation:
Identify the reader
Connect to the reader and understand what it takes to make him/her understand the product feature/s. One must step into the readers’ shoes or think the way the user thinks, while preparing the user documentation. I do not, in any way, intend to teach you what to write. The art of saying something is at times much more effective than the purpose of saying it. Additionally, it is possible that you might address two different levels of minds/users through one document. It is, therefore, necessary to prepare a document, which is neither too basic nor too advanced. You must use a narrative technique (which is the art of saying), so that you address readers, rather than addressing the functionality of the product.
A simple way of connecting with such contrasting levels is to start at the basic level, and, slowly, increase the level of complexity of document. Of course, it is possible that those who did not read the first few chapters will find it difficult to comprehend the last ones, but you always have techniques of cross-referencing content, so that readers get exposed to major part of your documentation, while referring to certain functionality. The readers might not click on the references, but they will certainly know where to look for, when in need.
Improve user experience (UX)
As far as the documentation is concerned, a picture is worth a thousand words. And a description of the picture will only add to the understanding. Adding pictures, to describe procedures and features, always helps. As far as the product is concerned, make the interface intuitive and simpler.
Grammar: To the rescue
A badly “edited” documentation is much worse than a badly “written” one. Editing, if performed on a detail-level, can fetch you with far better readability statistics. The following are some of the key points, as I understand:
Cut dead words: Prefer to not to include any such word, which does not contribute to the understanding of the user.
Use hassle-free writing: Prefer to replace anything that “has been” done with “is done”. Replace anything that looks like “a majority of” with “mostly”, “due to the fact that” with “because”, “in most cases” with “often”, and “in order to” with “to”.
Avoid “techy-ness”: Prefer writing in simple terms, so that you avoid losing your reader: Simply write “use” for “utilize” or “feature” for “functionality”. I remember having read (and revised) a lot of user documentation, which accidentally (at least I hope it was so) used words like “obligatory” for “mandatory”. I could only imagine the sorry-state of readers. Also, you should avoid forming noun stacks in sentences.
The help document, as is seen mostly, is never really helpful for readers – and for more than a reason. To minimize hassle, and the need for documentation, you should have tooltips – which are simple (and helpful) and intuitive – inserted wherever possible (and required).Also, some context-sensitive examples can be provided in the help documents, along with examples, to cover case-specific information, if any.
Single source the documents
You are always welcome to implement single sourcing in documentation. Reuse and republish content wherever possible and provide enough links/references. Single sourcing has far-stretched advantages in companies that release their documentation in different languages or those that have role-based user guides.
Use wisely the points discussed: You will talk less, but tell more.