Employ Engineers not Librarians

If you are running a software company today and are not heavily investing documentation, you are throwing money away. Far too often there is the attitude of putting off or completely forgoing full documentation in an effort to ship a product sooner. After all, spending time and money on documentation slows you down and doesn’t produce something that makes money. Should be skipped right? No, someone is definitely looking up all those corner cases rules and what that forgotten check box does, its one of your most expensive resources. Its your engineers.
But your company is full of seasoned experts, they know everything about the system and don’t need to refer to documentation, right? In my experience this has never been the case. I’m willing to bet they not only need documentation to refer to but, if you don’t have the information in an easily reachable place, they are sending emails to your engineers to do some digging. After all, the engineer has the code and at the end of the day only the engineer can see what is really going on. As a result, that time saved by skipping full documentation on a project will be spent several times over with interruptions.
There are many approaches to software documentation either all up front, filled out in detail at the end, or some ongoing process through out a development cycle; one thing is clear, there needs to be a single living document which describes a feature or set of features in an area. Where you keep and maintain software documentation is up to you (there are literally thousands of document management systems), although I have always been a fan of Wiki style pages. It all needs to be searchable so throwing them all in shared folders, no matter how organized, really isn’t a good solution.
Regarding document maintenance, integrating change orders down the line needs to be part of the software engineering process and should be considered in your estimates. An original spec with a scattered list of change orders is not a document. If a single change order gets lost, the behavior of a feature could be completely wrong and only compounds the issue and usually leads to defects being introduced.
Nobody, no matter how experienced or how good remembers everything. The smart people know how to look things up, so give them tools they need. Stop turning your software engineers into librarians and get serious about documentation.
If your team already is on top of things, I applaud you. I’d love to hear your approaches, do you have one person manage a project’s documentation. Do you have each key member from Design, Engineering and QA each contribute?
As always, if you’ve made it this far, I can’t thank you enough. I’m always available @KeyboardG and would love to hear from you.


1 comment

  1. KeyboardG

    I am really interested in good ways to influence change a fast paced companies who can’t seem to take a step back and look at the money actually wasted.

Leave a Reply