Document these sorts of things
- Requirements (features): Early on in the project, you should define what the client wants the product to do in specific terms. You can generate some requirements initially from brainstorming, but you should also engage your client in nailing down specific use cases to ferret out more detailed requirements. Also, explore all of the edge cases and exceptions that you can. This document should evolve with the project, because you can never know everything up front. Make sure you keep it up to date, because it should serve as the basis for testing and user documentation. The requirements doc can usually become the system documentation at the end of the project.
- Constraints: Make sure to express the limits imposed upon the project. What won’t it do? What minimum versions of other software does it need? What features that similar systems might provide are being intentionally excluded from this one? You can often include these constraints as part of the requirements doc.
- Commitments: The project schedule needs more than a verbal OK, and so does the allocation of resources. Write it down, whether it’s your commitment or theirs. You don’t necessarily need a formal document — email can work, as long as you can verify receipt and keep it organized for quick retrieval.
- Implementation: You should comment code, but only comment the non-obvious. You should assume that the person reading the comments is capable of reading the code, and avoid explaining commonly used algorithms or features of the language (unless they’re esoteric). You should explain “tricks” that might deceive the reader, and algorithms that may be difficult to understand. Most importantly, you should document your intentions — the “why” instead of the “what” or “how”.
- Documentation: Yes, you should document your documentation. Provide a map, so when the next person comes looking for something, they’ll know where to look. This can be as simple as a single web page that links to all of the project’s related documents.
What thorough documentation provides you and your client
- You know what you’ve got and what you don’t have.
- You’ve set clear expectations, so you reduce or eliminate unpleasant surprises.
- When someone comes along later to add a new feature, they can tell what’s going on (even when that someone is you).
Include documentation in your contract
Documentation doesn’t magically appear by itself, and I’ve never seen any evidence of the rumored Documentation Elves. So you need to allocate time in the project for writing documentation at all stages. Your client needs to be on board with that resource commitment, so include documentation as one of your deliverables in your contract. It’s a vital part of the product.
