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 software documentation and it can often be the deciding factor when purchasing an application.
Good Technical Writing
Good documentation will:
- Add credibility to products
- Prove to be a valuable sales aid
- Help users to learn independently
- Reduce support requirements
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?
There is a big difference between user guides that are written by a professional writer, and those that are written by developers. On the surface, it makes sense to get the people who develop the software to write the documentation - nobody knows the system better, surely? This is often the wrong approach - consider:
- Few developers have an all round, high level view of the application; they are often working on specific aspects, concerned with the mechanics of whether code works, not how it is implemented as a business solution.
- Developers like to develop; few enjoy writing and even fewer can do it to a professional standard.
I have produced many different user guides, ranging from highly detailed looseleaf publications to small CD inserts. I can design and write user guides from first principles, or update existing material in line with corporate style. Once the guide is complete and you are happy with the content, I can also arrange for professional print services.
I take the same, professional approach with online help content as I do for hard copy user guides, although the style of writing is usually quite different. I can create a new help system from first principles, or update existing help files as required.
A number of solutions are available, depending on the kind of application that you develop, including:
- Online help for Windows applications
- Web help for web-based applications
- Apple help for Apple applications
Bids & Tenders
Writing professional bids and tenders is a skill, requiring a definite writing style and its own phraseology. And when it comes to the finished article, looks definitely matter.
I can help with any stage of the bid writing process, whether you would like help at the very start to gather information, or if you have finished content that requires a final edit, or maybe you'd just like some help with document design or proof reading.