Help Files and Technical Documentation

I recently released version 2.4 of Complete Time Tracking. It was a fairly major release (despite the .1 version number increment) as with the update, which contains more than 30 enhancements, I released a new Professional edition for multi-user time tracking (the previous incarnation is now known as the Standard edition).

In light of this I am about to release a new web site for CTT which is a big improvement over the current site, containing more information, better layout, clear feature differences between the Standard and Professional editions, streamlined download and purchasing and so on.

Both of these efforts required a great deal of technical documentation. I do not claim to be an expert in technical documentation but here is my 30 second view and a few tips.

General copy (text) discussing product features should be written with the style "what not how". For example, you might write "Security access to more than forty features can be configured for each user" instead of "You can configure security access to more than forty features by selecting the user configuration option".

Conversely tutorials and instructional copy should be written with the style "how not what".

Web sites promoting your products should typically be written using "what not how", though it is often worthwhile to use "how not what" on FAQ pages and in online feature tours and video demonstrations.

Help files and user manuals usually contain a combination of the two styles. Users want to know both what is possible and how to do it.

A quite useful book for writing technical documentation is Microsoft Manual of Style for Technical Publications, which outlines which/what word forms to use, such as which vs. what, login vs. log in, can vs. may, when to use capitalization, guidelines for writing headings and subheadings and much more.

For help file creation I can highly recommend Help and Manual. Version 4 was recently released and contains some great new features. From the one help file project you can generate professional looking help files, PDF or MS Word user manuals, browser based help and more.

In all cases try to get someone else to review your copy. What sounds ok or is understandable to you might not be the case for other people. Take the following case as an example.

A user of Complete Time Tracking recently queried how to create categories. It is described in the online help but in my "how not what" email reply I said "Select the Configure Categories button on the toolbar...". The user replied "What is a toolbar? I only see some buttons along the top but nothing saying Configure Categories." The button icon and tooltip hint might not be as intuitive as I first thought. Perhaps I should have described how to perform the steps using the menu instead.