IT consultants, document your work!: "
A client called on me to add a new feature to their software: nothing too fancy, just a search function with multiple criteria. Given the nature of their application, I had to wonder how they had gotten along without it for so long. We spec’d out their requirements, and I implemented it at an hourly rate in less time than they expected, including documentation and testing. Everybody was happy.
A week or so later, the same client asked me to research an unrelated problem they were having. While looking through the code that had evolved from the sculpting of numerous hands over the years, I discovered a routine named LKPMCD. Perusing the all-uppercase comment-free code, the meaning of this cryptic name began to emerge. It was a LooKuP routine for Multiple ConDitions — almost identical in its function to the project I had just completed, though of course my code was better (it always is, isn’t it?).
The client didn’t even know they possessed this routine, because everyone in the organization who ever knew about it had moved on, and the documentation existed nowhere, not even in comments. Rediscovering the routine required a code archaeologist like myself to have the good fortune to stumble upon it and the curiosity to decypher it.
I bet you’re wondering whether I told the client that they wasted money on the job. Well, I did. First of all, I’d rather bring it to their attention than have someone in their organization discover it later and accuse me of fabricating the work. Better yet, though, I used the opportunity to make a point about the usefulness of good documentation. “Had anyone documented this routine anywhere,” I said, “you could have not only saved the cost of implementing it again, but you could have been using it all this time.” They concurred, blamed the former employees, and posed no objections to my bill.
To facilitate updating and sharing, you should consider using a wiki for this documentation. Passing PDF or DOC files back and forth is so last millennium — it requires unenforceable, exclusive locking of each document, wastes a lot of time emailing and saving attachments, and exposes that documentation to the security risks of email.
For tips on writing good documentation, read the TechRepublic column 10 things you can do to create better documentation by Alan Norton.
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.
"
A client called on me to add a new feature to their software: nothing too fancy, just a search function with multiple criteria. Given the nature of their application, I had to wonder how they had gotten along without it for so long. We spec’d out their requirements, and I implemented it at an hourly rate in less time than they expected, including documentation and testing. Everybody was happy.
A week or so later, the same client asked me to research an unrelated problem they were having. While looking through the code that had evolved from the sculpting of numerous hands over the years, I discovered a routine named LKPMCD. Perusing the all-uppercase comment-free code, the meaning of this cryptic name began to emerge. It was a LooKuP routine for Multiple ConDitions — almost identical in its function to the project I had just completed, though of course my code was better (it always is, isn’t it?).
The client didn’t even know they possessed this routine, because everyone in the organization who ever knew about it had moved on, and the documentation existed nowhere, not even in comments. Rediscovering the routine required a code archaeologist like myself to have the good fortune to stumble upon it and the curiosity to decypher it.
I bet you’re wondering whether I told the client that they wasted money on the job. Well, I did. First of all, I’d rather bring it to their attention than have someone in their organization discover it later and accuse me of fabricating the work. Better yet, though, I used the opportunity to make a point about the usefulness of good documentation. “Had anyone documented this routine anywhere,” I said, “you could have not only saved the cost of implementing it again, but you could have been using it all this time.” They concurred, blamed the former employees, and posed no objections to my bill.
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.
To facilitate updating and sharing, you should consider using a wiki for this documentation. Passing PDF or DOC files back and forth is so last millennium — it requires unenforceable, exclusive locking of each document, wastes a lot of time emailing and saving attachments, and exposes that documentation to the security risks of email.
For tips on writing good documentation, read the TechRepublic column 10 things you can do to create better documentation by Alan Norton.
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.
More about documentation on TechRepublic
- Move to a paperless system for client documentation
- Download: 6 steps to better software documentation
Comentários
Postar um comentário