Tag Archives: writing manuals

Answer Questions versus Writing Manuals – Why not do both!

If someone asks you how a product you are developing works, should you answer? They could ask via email, Jira issue, or in person. Is it better to shun such people, write product documentation, and tell people to go Read The Full Manual (and stop bothering you!) My preference is a combination of both. I […]

Documentation Sets

My last technical documentation post on remembering the audience reminded me of the importance of designing the documentation set for the product you are working on. Knowing the audience is a critical part of writing a manual. I like the approach of having a short introduction section where all manuals follow the same structure. Standard […]

Technical Documentation Writing

There are whole books written about technical documentation writing. Here are my key take aways. Make sure you know who the audience is before you write a single word. You are writing documentation for others, not yourself.  Put yourself in their shoes. Use terminology the reader will understand. Use short simple sentences. Long sentences get […]