On one of my mailing lists someone asked for guidance on creating software docs. I responded with a few simple principles:
- Less is more: People simply do not like to read this kind of stuff and so leave out anything they don’t need to know, such as theoretical discussions of why something is the way it is. Also, at least in the first release of docs, use the 80/20 rule and only document the main use cases rather than the exceptions. Think of this as paying rent.
- Pictures really are worth a 1000 words: Screenshots and even better screencasts are much better ways of explaining action sequences than text. Any time you’re putting a numbered list in the text, consider doing a short screencast instead or also.
- Fix the software: If you have a tough time explaining a feature or capability for the documentation then consider rewriting the software. The best documentation is software that needs none, the ultimate less being more.
- Steal or copy: Look at the documentation for software you use or is competitive or you respect and see what you can reuse from that, whether it’s formatting, how they use graphics/screencasts or method of explaining difficult concepts.
While screencasts are a very new concept I think they are a tool very much suited to our times. Already there are a bunch of free and inexpensive applications available for making them, all seem very easy to use, meaning a low barrier to adoption. If bandwidth costs are a concern for you or your organization, post them to YouTube or similar services–after all, the more widely available these videos are, the better!
Aptana has produced many and put up Aptana TV to host them (not to mention that site is the first production ActiveJS application, good job Ian and Ryan). Many of the videos are done by the developer who worked on the part of the product described, which I think is very powerful when the product itself is used by developers. No marketing fluff, at least.
BillSaysThis 