I’ll be on vacation in Canada from the 17th August to the 7th September. Orders will be processed automatically. I should get access to the Internet pretty easily there so I’ll be able answer to e-mails as usual (it may just take a little bit longer if I’m among the whales!).

Today, I have released a minor update for Direct Access, that addresses some issues and adds some little new functionalities. In particular, now you can directly add an Autotext Action from the Hub or the Notify Icon from the clipboard contents. Moreover, when adding or changing an Action a label tells you the command is already in use by another action. If you associate a command to more than an action, when you type it a menu is shown with all the actions associated to the command. For a full list of changes, see the release notes.

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

Today, 3rd August 2006, sees the release of the final version of Direct Access 1.0.

I would like to thank all the people at ASP, OISV and Business of Software Forum for all their suggestions and criticisms and, in particular, Martin, of The Documentation Doctor, who is a highly skilled and talented technical writer who did a fantastic job correcting and organizing the website and the Direct Access manual.

Direct Access enables you to set up meaningful keyboard commands for

• Opening applications, folders, and websites
• Composing emails
• Inserting autotext
• Open customized menus containing your commands

When it recognizes a command, Direct Access uses a tooltip to suggest an action, and goes ahead if you hit F1, the confirm key. You don’t even need to have open a word processor or editor. Just type a command and hit F1.

For example, typing “note” F1 could open Notepad. Typing “myname” F1 could enter your name as autotext in any application, even one without built-in autotext!

Learn more about Direct Access or download a free 30-day trial.