Technical writing

Can't our developers write the documentation?

You have staff members who know the system inside out so why shouldn't they document how it works? It's a fair question.

Technical writing is a skill. The fact that someone develops or works closely with a system does not mean that they are the best person to write user documentation. Often, the reverse is true because they are focused on code, not how the application might be used in the real world. An experienced technical author will:

  • Have an instinctive approach to learning new applications
  • Empathise with users and predict what areas might cause confusion
  • Pitch instructions at the right level (and in the right form) for different types of user
  • Make dry subjects interesting with careful use of language and presentation
  • Explain why, not just how
  • Use plain English, without jargon

People have high expectations when it comes to documentation and it can often be the deciding factor when purchasing software.

What does good look like?

Great technical documentation will: 

  • Add credibility to products
  • Prove to be a valuable sales aid
  • Help users to learn independently
  • Reduce support requirements
  • Put your software through its paces (aka free testing!)

There are many factors to consider when it comes to good versus bad documentation, including technical accuracy, clarity, structure, concision, style, consistent terminology, grammar, layout and design, illustrations, indexing and print format.

However, what often separates good from bad, is the the manner in which  features are presented. A bad user guide is one that lists every single feature in an application but fails to explain why anyone would ever need to use them.

Most software is built around a key idea, philosophy or concept; once you understand what these are, learning the application becomes much easier. Good documentation conveys these concepts, explaining features by putting them into context. It identifies real-world tasks that users will want to carry out and explains the process that should be followed to complete them.

To achieve this, a good technical writer will ask why? far more than they ask how?

How I can help

I can help with any type of software documentation, including:

  • Knowledge base content
  • Software user guides and tutorials
  • API documentation
  • Technical processes  and developer documentation
  • Training collateral

I use a range of tools, including:

  • Confluence & Jira
  • Zendesk
  • RoboHelp
  • Microsoft Word, SharePoint & Visio
  • Camtasia
  • Photoshop
  • SnagIT