Why is there No Documentation?
I’m surprised at the number of developers who don’t create any documentation. There are ways to self-document code and there are packages to add automatic help to an API to document the services. Unfortunately, that’s not enough. I’ve heard all the arguments:
- It chews up programming time.
- It rapidly becomes obsolete.
- The code should explain itself.
- As a programmer, I’m more valuable if I keep the knowledge to myself.
Let me explain what I mean by documentation. What should you document outside of your code? Every time you create a program you usually create a design for it. If it’s just drawings on a napkin, then it needs to go someplace where other developers can access it if they need to work on your software. Configuration parameters need documentation. Not a lot, just enough to describe what the purpose is. Installation? If there is some trick to making your program work in a production, QA or staging environment, then you should document it. Where is the source code located? Is there a deployment package? Was there a debate on the use of one technology over another?
So what happens when you have no documentation? First, you need to find the source code. Hopefully it’s properly named and resides in the current repository. Otherwise, you may be forced to dig through directories on old servers or in some cases the source might not be available. If the source is not available your options are limited: De-compile, rewrite or work with what is built. Looking at source code written by a programmer that no longer exists at your company is a common occurrence (did that programmer think not documenting made him/her valuable?). Usually such code is tightly coupled, contains poorly named methods and variables with no comments. So here are the arguments of why you should do documentation:
- Reverse engineering software chews up programming time.
- Most undocumented code is not written to be self-explanatory.
- Attempting to figure out why a programmer wrote a program the way he/she did can be difficult and sometimes impossible.
- Programmers come and go no matter how little documentation exists.
It’s easy to go overboard with documentation. This can be another trap. Try to keep your documentation to just the facts. Don’t write long-winded literature. Keep it technical. Start with lists of notes. Expand as needed. Remove any obsolete documentation.
Getting Your Documentation Started
The first step to getting your documentation started is to decide on a place to store it. The best option is a wiki of some sort. I prefer Confluence or GitHub. They both have clean formatting and are easy to edit and drop in pictures/screenshots.
So you have a wiki setup and it’s empty. Next, create some subjects. If you have several software projects in progress, start with those. Create a subject for each project and load up all the design specifications. If your development team is performing a retrospective, type it directly into the wiki. If there is a debate or committee meeting to discuss a change or some nuance with the software, type it into the wiki. They can just be raw historical notes.
Next, add “documentation” as a story point to your project, or add it to each story. This should be a mandatory process. Make documentation part of the development process. Developers can just add a few notes, or they can dig in and do a brain-dump. Somewhere down the road a developer not involved in the project will need to add an enhancement or fix a bug. That developer will have a starting point.
Another way to seed the wiki is to create subjects for each section of your existing legacy code and just do a dump of notes in each section. Simple information off the top of everyone’s head is good enough. The wiki can be reworked at a later date to make things more organized. Divide an conquer. If a developer has fixed a bug in a subsystem that nobody understands, that developer should input their knowledge into the wiki. This will save a lot of time when another developer has to fix a bug in that system and it will prevent your developers from becoming siloed.
You Have Documentation – Now What?
One of the purposes of your technical documentation is to train new people. This is something that is overlooked a lot. When a new developer is hired, that person can get up to speed faster if they can just browse a wiki full of technical notes. With this purpose in mind, you should expand your wiki to include instructions on how to setup a desktop/laptop for a development environment. You can also add educational material to get a developer up to speed. This doesn’t mean that you need to type in subjects on how to write an MVC application. You should be able to link to articles that can be used by new developers to hone their skills. By doing this, you can keep a new person busy while you coordinate your day to day tasks, instead of being tied down to an all-day training session to get that person up to speed.
Your documentation should also contain a subject on your company development standards. What frameworks are acceptable? What processes must be followed before introducing new technologies to the system? Coding standards? Languages that can be used? Maybe a statement of goals that have been laid down. What is the intended architecture of your system? If your company has committees to decide what the goal of the department is, then maybe the meeting minutes would be handy.
Who is Responsible for Your Documentation
Everyone should be responsible. Everyone should participate. Make sure you keep backups in case something goes wrong or someone makes a mistake. Most wiki software is capable of tracking revisions. Documentation should be treated like version control. Don’t delete anything! If you want to hide subjects that have been deprecated, then create a subject at the bottom for all your obsolete projects. When a project is deprecated, move the wiki subject to that folder. Someday, someone might ask a question about a feature that used to exist. You can dig up the old subject and present what used to exist if necessary. This is especially handy if you deprecated a subsystem that was a problem-child due to it’s design. If someone wants to create that same type of mess, they can read what experience was learned from the obsolete subsystem. The answer can be: “We tried that, it didn’t work and here’s why…” or it can be: “We did that before and here’s how it used to work…”
If you make the task of documenting part of the work that is performed, developers can add documentation as software is created. Developers can modify documentation when bugs are fixed or enhancements are made. Developers can remove or archive documentation when software is torn down or replaced. The documentation should be part of the software maintenance cycle. This will prevent the documentation from getting out of sync with your software.