Words To Live By

The First Rule of Documentation

  1. Fix it in the UI

The UI is the Application/Page because hidden features never get used. So one of the first rules of software coding is the related, “Fix the UI”.

Make it simple and intuitive, like anything from Apple and avoid as much documentation as possible. However, even Apple needs some text, and sometimes could benefit from using even more.

You Are Not Reading This Page

You are scanning a brightly lit screen. The extra light you are staring at makes the words  approximately 3X harder to read than ones on paper.

The smartest programmer I ever met, set his computer display preferences for a black background like this one, with text white by default to ease the strain on his eyes. This replicates the old-school computer monitor displays back before Steve Jobs invented the white “just-like-paper” standard that we take for granted today.

Text needs to be sparse and short to be scanned and understood by an online reader. Technical writing on paper can also benefit from cutting every unneeded word and using simple language.

Write Better With the Seven ‘C’s

  • Complete
  • Correct
  • Clear
  • Concise
  • Consistent
  • Convincing
  • Considerate

Use plain, simple language to make instructions direct, easy to scan and understand. Even the US Government says it’s OK.

Write Once Read Everywhere

Content needs to appear on multiple browsers on multiple devices. Design for all kinds of sizes with adjustable percentages and separate the content (words and illustrations) from the presentation (fonts and frames), and simplify, simplify, simplify.

The Agile Content Lifecycle in Nine ‘R’s

  1. Requirements (get)
  2. Research (audience + subject)
  3. Reproduce (the knowledge)
  4. Reduce (cut the fluff)
  5. Research (test)
  6. Revise (heed the results)
  7. Recall (find the info or fail)
  8. Repair (update)
  9. Reuse (component-ize with topics)
  10. Repeat

Notice the use of research at two stages. Research your audience and test your product to make it user focused. Recall depends on good metadata. Remember that information not found is a waste of money and time. With search now replacing the table of contents as the most used way to find information, every page is now the first page.

You can save time and recycle your content if you make it into a collection of reusable components. Darwin information typing architecture (DITA) is a standard similar to XML for online documentation. There are three basic types of components: concepts, tasks, and reference materials. They are also known as “topics”. Each topic is a chunk of content that should have everything you need to know about the subject right there, and linked to related topics. This makes updates much easier as each topic or link can be changed individually. Inserting or even swapping new material is also faster.

Publishing is not the final stage. The content must be updated regularly or retired.

Reiterate the process to stay agile and up-to-date.