The aim of a how-to document can vary greatly. There are development documents, application documents, and end-user documents. Each has its voice, and each has its challenges. In every case, the material must be accurate up to the publication date, and revised as needed at set intervals or at trigger points.

For a developer document, notes are good, but they don't have to be smooth. There's a language among developers and programmers that is akin to the language of math, or a distant land; if you speak it, you don't need it interpreted, you just need it to be right. Devs like the bare-bones approach most often, and willingly accept commented, nicely ordered command sequences.

Application documents are normally written for a staff group, such as the IT staff of an organization. These documents need to be prefaced and commented well, and organized. The preference is for smoothly flowing order, succinct commentary, and just enough filler for a low man on the staff to be able to use the document.

End-user documentation needs to include more detailed commentary. In addition, a page that includes a fair number of images to clarify the necessary code is almost critical. A picture is definitely worth at least a few paragraphs, if not a thousand words. The end user may not be familiar with any of the tech, or they might be a developer. They may be anywhere along the spectrum of experience.

Our documentation aims to be accurate, timely, useful, and aimed at the end user. We assume our end-user will have some level of experience with this technology, and may be from either a business or an academic background. We know that our end-users are smart and well-educated, but we extend the style of documentation to reach even more people. The clarity and flow are there, and background, too.

Enjoy!