Project Management

IT consultants, document your work!

Chip Camden lists three benefits of creating thorough documentation for your clients. He also identifies what sorts of things you should document.

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

About

Chip Camden has been programming since 1978, and he's still not done. An independent consultant since 1991, Chip specializes in software development tools, languages, and migration to new technology. Besides writing for TechRepublic's IT Consultant b...

30 comments
Satur9
Satur9

Good luck consultants getting documentation in a wiki when developer employees can't even get a wiki server instance authorised! I suggested using wikis to hold documentation and less formal information, but management rejected it, so documentation is still ad-hoc and in word documents, sigh! Ironically, it appears that the corporate Intranet of the PLC, which took over the company I work for, does use some form of PHP wiki, however I'm not sure which one.

alxnsc
alxnsc

Dear colleaguues, this articlee lists requirements, constrains, etc. but misses the main. The main is always the goal, the aim. Documentation first line has to be the definition of purpose...

PMPsicle
PMPsicle

Chip you include ... * Requirements (features) * Constraints: * Commitments: * Implementation: * Documentation: But the one thing you don't include is changes! Being able to identify the changes that were introduced (e.g. project scope, revisions, redesigns, your corrections) is one of those "save your a**" type of things. Being able to document the requested changes is the only thing that's saved me on many projects.

sysop-dr
sysop-dr

Code and documentation only go so far. And a lot of us don't like to do documentation, we would rather be coding, but you have to do it. So I turn to tools to do all of the heavy work for me. I write code in this process. First make sure what you start with (if not starting from scratch) is in some type of config management tool. It really doesn't matter which one, just pick one. If possible pick one that also has requirements management, work flow and can export change comments with code comments against changes and if possible change requests. By linking your requirements to change requests to code, (to testing) you can show what work you did, why and how it was done and tested. And then the good CM packages also let you export all of that into the document format of your choice and then you put some words around it and you have your documentation. Configuration management when done right saves you time. It also so saves your sanity and you can use it to show your clients progress. There are lots of tools out there, get them, learn them, use them.

reisen55
reisen55

I make weekly visits to a few clients and, on each visit, I keep an easy to modify CHECK LIST of things to do. Helps me remember and also is a document I distribute to my clients as a "keeping them informed" paper. I can also add editorial comments as to why certain critical tasks are done. Secondly, we poor humans have not had a memory upgrade in a few thousand years or so, or more - and we forget. Document software resolution issues. I keep an IT PROCEDURES folder at client sites and always write up a HOW TO DO IT procedure before, in six months time, I realized I DID IT ONCE before but cannot remember NOW. A very good thing to do.

bhicks11
bhicks11

Good advice Chip. It's part of the job - I do a lot of MS Access programming and customization at my home office for customers. They deserve a breakdown of what they are paying for. http://www.dataplus-svc.com

Sterling chip Camden
Sterling chip Camden

... as contrasted with cowboy coders who hear a request, respond with "sure, we can do that" and start the keys a-clicking. They usually end up with no documentation whatsoever beyond the code itself. What's your doc plan?

Sterling chip Camden
Sterling chip Camden

And that documentation needs to go beyond "what changed" to include why it changed and who requested it. Source code management software automatically documents the "what" -- the "why" and "who" require additional effort.

JimTheEngineer
JimTheEngineer

"Six months???" I figure I need written help after TWO WEEKS or so! I have also been in the situation where the client had developed a new piece of hardware which I was supposed to work on, but no one had written down much about it. I ended up asking the developers about it, writing a tentative documentation sheet, passing it back to the developers, and going back and forth until we were all happy with it. When I returned later on another project, I noticed that the documentation on that chip was basically what I had written...but without my name on it. Oh well - they paid me for it. ("There is no limit on what you can accomplish as long as you don't care who gets credit for it.") - Jim

Sterling chip Camden
Sterling chip Camden

We've actually experienced memory atrophy because of our reliance on the written word. Although there are ways to improve your memory, there's now too much information to keep everything in our heads. We have to write things down, so it pays to do so in an organized, intentional manner.

TheComputerator
TheComputerator

Documentation is one of my pet peeves. Or, rather, lack thereof. We brought in a consultant to do a major overhaul of a database he'd designed originally about 5 years earlier...with no documentation. I kept telling him and telling him I wanted documentation but I never got it because his time/budget ran out. More than 6 months of coding and not one word of documentation. Made me cranky...

cmaritz
cmaritz

... all IT practitioners, document your work! This is good advice for just about anybody. One thing that stood out for me was in the Implementation part to include the 'why', in addition to the 'what' and the 'how'. I often miss that step. You taught me something today, Chip. I'm going to start doing this TODAY. On the subject of goals, a couple of people mentioned that your steps are missing a 'goal' upfront. Although, you do begin with 'Requirements (Features)', which I guess presupposes some goal or result that the customer wants to achieve. Actually we are busy rolling out a project management methodology in our hospital. Something interesting that the providers say you should do upfront, is to write down a narrative of the goal. Meaning, pretend you are the customer and you are now using the new program or feature (or whatever it is the project is supposed to provide), and write down the experience in plain language. Include all the good things that make your life so much easier, now that you have this new thing as developed by Chip Camden! It's like a vision statement, but a bonzai version, specifically for the project. From that statement, 2 things should be derived: 1) Requirements/features (which you have) 2) How to recognise when you have succeeded (!). Amazingly, it happens often that a project comes and goes, and then someone asks, "So did the implementation of XYZ work?" and some say yes and some say no, and some don't even know. Because, the success factors were not clarified up front. It's no surprise that the same projects are often the ones that go on and on, way past their deadlines and budgets. Anyway, that's more about project management, which is another story. But it's also kind of the same story too. Thanks Chip for sharing more good stuff with us and promoting discussion. Cheers, C.

tssi
tssi

... they can read the code. :-) Ran into this a few too many times. I document my code first, describing WHAT it's doing, then I fill it in with the code. I know I won't have time to document the code after it's working so I make time up front. The customer will wait for the working code, but not for the documented code. Same for any user documentation. I write it first, get it approved, then write the comments/code to match.

reisen55
reisen55

Raymond H. Eisenhardt Sr., wrote the phrase that is on the plaque in Reagan's Oval office and also a plaque given to Robert Woodruff of Coca Cola. Bronze plaque, small. Reagan got his through Justin Dart of Dart Industries, who my grandfather met on business and Coca Cola was a client of his company in 1959. Both Dart and Woodruff received a plaque as a thank you. "There is no limit what a man can do or where he can go if he doesn't mind who gets the credit." Always got me tiffed that both Reagan and Woodruff get the credit.

Dr_Zinj
Dr_Zinj

I'd love to try an experiment with a hundred people from a pre-literate society and see just how well they could function in the modern world without the use of writing. (Implementation would require interaction be via voice only, or at most, a descriptive diagram - ala a stick in the dirt.) But where the heck can you find 100 pre-literate, normal-functioning people now-a-days? And I don't mean graduates from the D.C. public schools either.

Sterling chip Camden
Sterling chip Camden

I'm glad you found it helpful. You're right about establishing goals up front, and those too should be documented and drive the requirements.

Satur9
Satur9

I've seen lots of code where the comments are misleading or just plain wrong, so code comments are useless if they are not maintained along with the code! I prefer to write my code so it is uses intuitive names for variables, methods/functions, classes, and packages (name spaces), so that it is self-documenting, only adding comments as required. Too many comments just add noise and make the code less readable, and harder to edit, as a whole. I have also found that static analysis code checkers (e.g. the NetBeans plugins for PMD and FindBugs *) not only help improve the quality of code, but also assist making it more readable and better documented. * see: http://sqe.dev.java.net/updatecenters/sqe/catalog.xml.gz https://sqe.dev.java.net/updatecenters/sqe/updates.xml

Sterling chip Camden
Sterling chip Camden

Documentation Driven Development -- I too find it useful, in conjunction with Test Driven Development. I often do both.

JimTheEngineer
JimTheEngineer

Thank you for the correction. I like to give accurate credit when I can. I remembered the phrase, and tried Google to find the quoter. It just reaffirms that "the internet is the greatest source of misinformation in the world." Yet, the internet is also a wonderful way of learning more. I use it...but with a bit of care. (It took quite a bit of search word adjustment to find a reference to Eisenhart with that phrase: "raymond h. eisenhart there is no limit to what you can accomplish" - but without the quotes.)

Sterling chip Camden
Sterling chip Camden

... because we've shaped the world around our writing implements. But neither could we function in theirs, which was shaped around their lack of same.

Tony Hopkinson
Tony Hopkinson

and try to come up with an agreeable name. If the function changes so does the name. The nature of what we do, (maintain legislative compliance) means change is more of a given in our job than any other one I've had in an extensive career. We are 'always' changing the code, the requirements we have to meet change frequently and with no reference whatsover to our implementation :( It's extreme (dictionary definition :D ) environments that push processes and ours pretty much pushed annotation right out of the door. I used to be naming and standards loon before I arrived, now I'm bordering on psychotic. VS2010, Right click refactor rename, the hard bit is coming up with a suitable one, when you do, job done...

Tony Hopkinson
Tony Hopkinson

not a documentation mechanism. Most problems with comments come from trying to bastardise //. Why is never useless, even if it seems entirely obvious to you at the time of writing. It won't be in a month or two if you are cranking out at great speed that can go down to days. What as in say doc comments, swings and round about that one. We have a policy of doing them, but where we need something beyond a well thought name is rare. Comments were invented when your code was LDX 01EE or LET X = 480 There are far more powerful ways of achieving that functionality in modern environments, how and what annotation are a cop out in my opinion.

Sterling chip Camden
Sterling chip Camden

If your variable names are highly descriptive (which they ought to be), then you must change them as their function changes, or they're just as misleading as an expired comment. How many times has a section of code proven to be more broadly applicable than the original use case, but not had the names adjusted accordingly? Then some git adds an explanatory comment that the name is historical.

Sterling chip Camden
Sterling chip Camden

... useless. But whenever you need to explain an algorithm (and in the work I do, that happens pretty often) then comments are useful. You do have to keep them up to date, though. Certainly if you can make the code plainly state what you're doing, that's better. But code often has a hard time saying "why".

Tony Hopkinson
Tony Hopkinson

I once posted here that I viewed comments as a failure. Got absolutely slated by some of the you must comment everything types. We make comprehensive use of the code quality tools that come with visual studio, aside from making your code better, they enforce a standard which once you get used to writing to it out of self defence, enables comprehension. Even trivial stuff like EntityID should be EntityId saves time in case sensitive code once you develop the habit.

Sterling chip Camden
Sterling chip Camden

... that a methodology that focuses on documentation would get their own right.

PMPsicle
PMPsicle

When I did coding on a frequent basis rather than a "you're willing to pay whaat?" basis ... I used to design my code using pseudocode. I often designed the pseudocode using descriptions. So in effect my (inline) documentation consisted of commented psuedocode. Overkill but if you couldn't figure out what I was doing you needed to get out of the biz. (Yes, this was in addition to my regular (paper) documentation).

ian
ian

Always interested in learning how others do things, I took a look at Documentation Driven Development and, being the pedantic person that I am, I couldn't fail but notice the errors in the title and the second sentence. "Documenation" should surely read "Documentation", "It is similiar to making an excact concept" should read "It is similar to making an exact concept" and "on the user then on the" should read "on the user than on the" Only grammatical errors, but enough to highlight the need for checking before publishing. Are there also typo's in the code?

Editor's Picks