Five Easy Ways to Improve Your Docs: Part 4, Mnmlsm

How’s your PDF looking these days? Maybe getting a little . . . thick? Taking two reams to print that puppy out? Clogs up your internet pipes when you try to send it around? Filled with dense scrawling paragraphs that bleed your toner dry? Sounds like your PDF needs a good dose of minimalism!

In the literary world, minimalism is the style of Raymond Carver, short, direct statements and observations delivered almost without affect, and yet conveying the deepest of meaning, all wrapped up in a tight gem of a short story. The same qualities that mark the work of Carver, Hemingway, and other masters of the minimal should also be the standards for technical documentation, both in style and structure.

• Follow the writing workshop dictum of cutting every sentence in half.  How many words do you really need to convey an idea or a step?
  
  
• Use consistent verbiage in relation to interface controls, so that you can imply what kind of control the user should be looking for without having to name it. If you always use “click” as the verb in relation to a button, for example, you could write “Click Send” rather than “Click the Send button.”
  
  
• Don’t create task topics for “modifying,” “editing,” or “deleting” anything unless there are no clearly labelled controls or interface elements for doing so, or there is something particularly complex about the task. Chances are that your users will only care about “adding,” and that they will understand what it means to “delete,” and that the content of “adding” tasks also applies to “modifying.”
  
  
• Keep the content of your topic to one specific task, concept, or set of references. Ideally the reader should be able to consume it “in a glance,” and determine whether it contains the content s/he is looking for. Nothing breeds verbosity like trying to convey too many ideas in a single topic.
  
  
• If you have the ability to use inclusion mechanisms for content, always be on the lookout for ways in which you can write once, and re-use many times. This will likely involve analyzing what the minimal shared content “units” are among your topics, and then finding ways to combine them to create complete topics.

Taking a minimalist approach to your documentation not only saves you work in the long run, but also substantially increases the usability of your docs by making it easier for the user to find and consume the information s/he is looking for. Brevity is at the heart of wit because it gets directly to the point, and while your docs may not elicit laughter, keeping them minimal may elicit the appreciation of your customers for the effort you put into their usability.