Ecommerce and Entrepreneurship Blog | About | Contact | Store

The Importance of Documentation in the Workplace

Posted on April 7, 2009 by Trevor

Documentation, the recording of organizational structures, policies, actions, and goals, is vital to any business, and doubly so for those of us in development. When I came on board I inherited roughly 200,000 lines of code that I had to learn well enough to find and pinpoint individual errors, within the span of about a week. While experience and clues from within the code help somewhat, the job would be nearly impossible without documentation of some kind. And documentation will continue to be important going forward: with so much to manage, it's unlikely I'll remember exactly what a particular piece of code does even a few months down the line unless I leave some easily understandable record. Even outside of the development world, documentation plays a fundamental role in business. It codifies procedures, ensuring everyone in the company does things the same way (hopefully the right way!). It streamlines processes, allowing people to look up answers instead of asking coworkers or reinventing the wheel. And it acts as protection during audits, helping to pinpoint any actions taken against policy. So, how should documentation be developed and integrated into your business practices?

First, it's important to develop your documentation alongside the actual process. Too often developers take the attitude, "Code first, document later." That would be fine if we could stick to it. But in practice it tends to become, "Code first, then code something else, and put off documentation for another time." Instead, you have to consider documentation a priority, updating it while the work you've done is fresh in your mind. Will that make you work slower? At first, yes, but over the long run it should save you time. Instead of thinking of documentation as something that hampers your real work, consider it as part of that work. You can't set aside part of your job because it's slowing down another part.

Second, streamline your documentation process to require the least amount of extra work. It's especially important not to duplicate information. When I'm documenting code, for example, it's often possible to intersperse the code and the documenting comments so that half of the documentation is the code itself. That way I'm not duplicating information by writing it once in code and once in the documentation. Another possibility is to set up automatic documentation procedures, so that you only need to manually fill in specific information. I have a Google document to record changes I make: it automatically fills in several fields for me, and other fields are set up to ease entering that information. This took a bit of extra effort to set up at first, but it reduces the ongoing work.

Third, be sure to structure your documentation. If you're documenting your work as you do it, it's likely that the documentation will be close to the actual work, both in detail and in location. That is wonderfully helpful when you're already looking at a specific piece of work, but what if you're trying to find that piece among all the rest? For that, you need higher-level documentation that gives the general structure of your work, explaining each piece and where to find it. It might also be helpful to give pointers to this general documentation from the specific pieces so you will be able to follow it back. However you choose to do it, make sure that your documentation gives a clear starting point to someone who doesn't already know what they're doing. Hunting for the right documentation is often just as frustrating as trying to understand the work itself.

As I come to grips with the code I have to work with and the duties I'm expected to perform, I'll be reading, updating, and creating the documentation to go with them. I'm hoping that with these principles I can efficiently create documentation enabling me and anyone else who reads it to get up to speed quickly and get the work done.

blog comments powered by Disqus