Who Writes the Documentation?

If you're a one-person shop, you may have to write your own documentation. At larger firms, there's often a technical writing department that works with the software teams to develop documentation.So

Some firms prefer outsourcing the writing so employees can focus on writing code instead.

Writing Documentation Well

No matter the type of program documentation, you want it to be clear, readable and helpful. There are several things to keep in mind:

• Make it easy to find all the types of user documentation you've written. For example, you can turn the ReadMe file into the root node from which users can find and explore all the different levels of documentation.

• Update your documentation whenever you update your code.

• Watch for bugs. Test out the documentation thoroughly and try any code samples you include. If you find problems, fix them.

• Write well. You want documentation to be clear, understandable, and easy to follow. Don't bog down your documents with technobabble and stiff writing. Even in technical writing, a human voice makes readers more comfortable.

• How well do you know your product? If the software is a team effort, work with the software until you're satisfied that you understand all the features. If you don't know the features, writing about how to use them will be difficult.

• The look of a document affects how easy it is to read. Long blocks of text with no indentations encourage eyes to look away. Break up text with paragraphs, diagrams, and illustrations.

• Be concise. You don't want to skip over anything important, but readers will appreciate getting to the point swiftly.

• Add visual aids. Screenshots and video instructions are often better teaching tools than text.

Added Online Documentation

In the internet era, you don't have to stop with a ReadMe file. You can also provide added types of program documentation on your website.

• If the website includes a blog, use that for added discussion of the software and what it can do.

• If you get questions from users, incorporate them into an online FAQ. This helps users and saves you time in dealing with individual queries. You can use the questions to shape updated versions of the user guide down the road.

Managers and Documentation

Even if project managers don't write the documentation, they need to oversee it. Errors in documentation can lead to users making mistakes or to the finished documents not matching up with the vision of the stakeholders.

Some managers choose to draw up detailed documentation before forging ahead with the project. This can be effective if the product doesn't change much from conception to final form. If there are changes, however, the team will have to work to keep the documentation updated.

The alternative approach is to produce documentation just in time. Work on the software and then document what you've done when that's what you need to advance to the next stage. This has become the preferred approach because it prioritizes work on the software, and the documentation stays current if the project changes.