Create a User Manual With a Documentation Tool

Components of Great Documentation

  1. One of the key elements that makes documentation good is clarity. It helps make content useful to the end user. To achieve that:
  • Be concise. Use a phrase instead of a sentence where possible don’t go off on a tangent. The shorter the writing, the easier it is for readers to grasp the most important concepts.
  • Have a unified style. It is inevitable with large-scale projects to involve multiple developers or other team members. So an editor is essential in such cases so that the writing style remains consistent throughout the manual. Otherwise, different terms will be used for the same concepts, and the same process will be described in different steps.
  • Editor. The page editor should be familiar if you’ve ever worked with MS Word. It’s called a “what you see is what you get” editor or WYSIWYG. That means the formatting tools such as font size, bold/italic, and spacing are all usable as if they were a word processor.
  • With the comments feature, your colleagues can see your draft and quickly let you know what they think. That review process is imperative for writing clear online documentation helpful for users from all backgrounds. The more eyes you have on your articles, the more useful they’ll be.
  • Versioning. When you write user documentation, it needs to be updated frequently to match the development of your product. And if there are several people working on a document with no centralized place to manage different versions of the documentation, things can get complicated. Inevitably, someone will create their version with their changes. A couple of cycles of that, and it’s a nightmare trying to get it back together in one piece. It happens pretty often that two people have their own visions for one document and haven’t gotten together to collaborate. Since you can easily see which version is the “latest” and which version is published, this confusion should be greatly reduced. This can be a good auditing tool to see how much gets changed over time as your team improves the articles. Are they mostly making minor cosmetic changes, or significant overhauls happening all the time?

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Bradley Nice

Bradley Nice

15.4K Followers

Content Manager at https://medium.com/level-up-web 👈. I write about web design, web development and technical writing. Follow me on Twitter and Facebook