Nine things I learned about writing software documentation
Writing software documentation for Direct Access has not been easy for two reasons: I’m not a native English speaker and I don’t have a complete mastery of all the nuances of the English language; I’m a programmer which has the tendency of using a lot of technical terms (I cannot help myself!).
So, recognizing my weaknesses, I looked for help and I found a Scotsman operating as Documentation Doctor. He is a talented and skilled technical writer who helped me rewrite the online documentation of Direct Access but also made a great deal of work fixing typing errors, reorganizing contents and adapting my geeky language to be comprehensible by the average user. All this was done with a great professionalism and a quick exchange of email messages.
Here are the lessons I learned. I lifted same examples (and corrections) from the Direct Access manual.
Show, don’t tell
This is the first rule. Demonstrate how to do things with clear and concise instructions. Avoid embarking in long and abstract explanations.
Less is more
Using less copy to express your concept will result in a more economic and efficient communication.
Reduce the use of screenshots in your help file
Although screenshots are good for a printed manual, they take a lot of screen space. Reduce them to the bare minimum. On top of that, having to update all the screenshots when something changes in your program, is also a major burden for you.
Avoid needless technical terms and explanation
If your software is aimed at non programmers, avoid technical terms as much as possible: they pose a barrier between you and your prospects. When people are confused, they don’t buy.
Avoid convoluted English
Use a direct and simple language, use the present tense and avoid the passive form.
FIRST TRY: Direct Access associates words (called commands) to actions, so that when a certain word is typed, in any application, it can execute the appropriate action.
BETTER AS: Direct Access enables you to specify words (called commands) to trigger actions whenever you type them. This works for any program.
Capitalize screen element names
FIRST TRY: context menu
BETTER AS: Context Menu
Avoid redundant words
FIRST TRY: Group: Indicates what group in the hierarchy contains the action. This column is shown only when the All Actions group is selected
BETTER AS: Group: The action belongs to this group. Only displayed when All Actions is selected
Give navigation details in logical order
When you direct users through menus and windows, start from the general to go to the specific.
FIRST TRY: uncheck the command confirmation in the Actions Panel for the desired action
BETTER AS: in the Actions panel, uncheck the command confirmation for the desired action
Use imperative for field description
FIRST TRY: Parameters (optional): Optional parameters that will be passed to the application. This is generally used to start an application with a certain document.
BETTER AS: Parameters (optional): Pass these parameters to the application. This is generally used to start an application with a certain document.
In conclusion, these are just some basic guidelines for your documentation. However, if you are not very experienced at technical writing, whether you are an English native speaker or not, taking advantage of the help of a professional will improve the quality of your technical documentation. Your customers will thank you for that.
Technorati Tags: Techincal writing, software documentation
6 Comments so far
Leave a reply
Nice post Andrea!
Nice tips. Here’s mine:
1. If you’re not a native speaker, unless you’re bilingual, forget about writing documentation. Natives will tell right away that it wasn’t written by a native speaker. If it’s a commercial product, they won’t like it, and insist on having it written by native speakers.
2. Even if you’re a native speaker, most people can’t write, especially literary and technical stuff. It’s a real job
3. Read the classic “The elements of style” http://www.amazon.com/gp/product/020530902X/
For me, non-native English, the FIRST TRY is more understandable then the BETTER AS honestly. Most of non-techie and non-native English people may not know what does trigger means (I know though :-)):
FIRST TRY: Direct Access associates words (called commands) to actions, so that when a certain word is typed, in any application, it can execute the appropriate action.
BETTER AS: Direct Access enables you to specify words (called commands) to trigger actions whenever you type them. This works for any program.
Well, of course being a native speaker helps a lot. This is why I decided to have my manual revised
Dennis, apart from the term trigger (any suggestion on alternative words I can use?) I think that the second try is more direct.
[...] Something Andrea noticed - I’m a great believer in showing, rather than telling. [...]
[...] You’ll note that the instruction is terse, without even a “simply…”. Since the feature really is easy-to-use, we can let it stand on its own merits. In fiction, this is known as show, don’t tell (something Andrea Nagar identifies as one of the rules of good documentation). [...]