The Way We Work
December 30, 2009 by Alex Hornbake

If you had never seen a hammer before, would you be able to guess how to swing it? Regardless of how obvious it may seem to you, the materials you are delivering to your clients may be brand new to them.

A properly documented project is a more powerful project. Whether it's a website, an application, or a server installation, the solutions delivered are only as valuable as the knowledge shared alongside those solutions.

While documenting the internal operations of a project is an important topic, I'd like to focus on the materials being delivered to a client. If you're a project manager looking to keep better internal documentation of your projects, consider using an online solution like BaseCamp, ActiveCollab, or ProjectPier; they can give you a central hub for communications, documents and schedules, and allow you to archive the project when you're done.

Budget Resources for Documentation

Project documentation and training go hand in hand, and both are essential to the value a project. Regardless of how you label it ("transfer of knowledge," "user education," or "documentation"), it has to be budgeted for and is a crucial part of bidding for any project. For commercial offerings with traditional reference materials, consider hiring a good technical writer, and for smaller custom solutions you can use a skilled editor to review your documentation. The type of documentation will depend on the project, but when offering bids, don't make the mistake of overlooking documentation.

How to Document

Be clear, concise, and remember your audience. Be thoughtful about what your clients will appreciate the most, and what will be easiest for you to deliver. In his series on "Writing Great Documentation," Jacob Kaplan-Moss has some excellent tips on software documentation; it is definitely worth a read.

Reference-manual style documentation can be great, but unfortunately it often goes unread. Consider that tutorials, and/or screencasts may be the best way to show your clients how to use a product. The goal of documentation is to give your client the knowledge they need to make the most of the solution you've provided them. Screencast.com and their Camtasia software are a well-respected commercial option and Screentoaster.com is a free screencasting tool worth checking out. Be sure to discuss with your client how they would most appreciate receiving documentation, and then deliver to meet their expectations.

Commenting Code
Depending on your client, they may never see comments, but eventually someone will. (If you're wondering what I'm talking about, "Comments" are the internal documentation inside of a computer application, written by programmers.)

Quick Tips for Better Comments:

  1. Use good naming conventions for classes, functions, variables, etc, and your code will be easier to understand, and need less commenting.
  2. Don't over-comment. Obvious statments like x = x + 1; don't need the comment // add 1 to x.
  3. Pick a style and stick to it. Consistency counts.

The subject of commenting code is too broad for a single blog post, but the following are some great resources for further reading:

Happy Clients
Good documentation will educate your clients. Knowledgeable clients are happy clients. Happy clients then come back to you and refer more business. Take the time to create clean and clear documentation—it's an often-overlooked investment of time and resources, but can provide excellent returns!

Alex Hornbake

Freelance Tech Writer

Alex Hornbake is one of several freelance writers on the oDesk Blog team. He joined the oDesk marketplace in 2009, and brings more than a decade of technical expertise to his clients. Alex shares his point of view to help you make informed decisions for your personal and business technology choices.

  • http://www.ricerealitycheck.com maicle

    The article is very interesting, may be i can't read at all now but continue at home. As a programmer you got my attention. Thanks for sharing great article.