Software Publishing: Writing The User Documentation Of Your Solution

From Dwayne Wright - Certified FileMaker 9 Developer
TWITTER: dwaynewright

This is part of my ongoing series of articles about setting up your own software publishing business (cause FileMaker is very good option for doing that). This was originally published by me in a guide called FileMaker Software Publishing back in 2002 and I’ve edited it slightly. .

There are many good reasons to write user documentation for your solution and many of them don’t have anything to do with informing your users how to use your database system. The process of documenting your solution can be part of your testing process. It can reduce technical support phone calls and emails. It can raise the satisfaction of the product to your clients, which makes the marketing of upgrades easier and creates positive word of mouth advertising. However, many times user documentation is considered one of the least priorities of a software publisher. Many times, the good and the great are separated by the quality of the user documentation and tutorials.

One way to start off is to look at the help documentation you have used for various software applications you use ( MS Word, Quicken, etc.). If it’s a manual, a tutorial, a getting started guide or a third party book you purchased, take a look at how it is written and organized. Which did you like the best and which did you like the least?

For example, go to your local bookstore and see the differences in the way books such as the Bible Series, The Special Edition Series, The Visual Quick Start Series or The For Dummies Series of books go about teaching their material. All of these books can be great examples of effective documentation for a computer software application.

Another technique is to have what you wrote … read to you by your computer. I use a
Macintosh in most of my production work, except for when I’m doing consulting work
for a Windows based solution. On a Macintosh, it’s very easy to use TextToSpeech to have a document or a selected section read to you. As you follow the words as it’s reading, you can experience what it’s like to be the audience. This allows you to easily edit sections that just do not sound right. There are software applications out there for Windows machines that do the same thing and I think that perhaps Windows XP may have this capability in the OS like the Macs currently do.

You might also want to include screen shots of what you are discussing in the documentation. This presents problems if your help system is an interactive FileMaker file but there are some workarounds. If you do want to use screen shots, I’d recommend distributing that documentation in html or pdf files.

Finally, you can make tutorial movies with narration to help educate your users. I’ve used Camtasia on Windows machines but wasn’t that happy with it. It could be that I’m more of a Macintosh person and use two screen capture utilities the most. The first is Snapz and it has been around a very long time. The second is relatively new called ScreenFlow and does require a new Macintosh running Leopard. At the time that I’m writing this, I’m experimenting with other movie making tools as part of a method to document my solution.

As we discussed earlier, it is a good idea to have your documentation examined by a third party. You might want to ask a professional copy editor to do this, may ask you solution testers to do this or do both. You are looking to get feedback on grammar, spelling, usage and clarity of thought. The more people that examine your documentation before you release the product will equal to better documentation and a better product.

More info about the author and FileMaker in general, contact me at

© 2008 - Dwayne Wright -

The material on this document is offered AS IS. There is NO REPRESENTATION OR WARRANTY, expressed or implied, nor does any other contributor to this document. WARRANTIES OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE EXPRESSLY DISCLAIMED. Consequential and incidental damages are expressly excluded. FileMaker Pro is the registered trademark of FileMaker Inc.

====================== ADVERTISEMENT ==============================
Check out the FileMaker Calculations Explored blog at or subscribe via your news reader. ===================================================================