If I had ever thought I would be doing a post on documentation, I would have made sure to have more topic starters in the back log. Let me put this out in the open, I hate writing documentation. Now that that is out of the way I feel empowered and what better way to express that than by judging all of you. I am going to guess that a great many of you hate documentation as well. Now don’t get put off by that statement or think I am belittling anyone in particular. I have seen it everywhere, on projects big and small, proprietary and open source, useful and utter garbage. Even my own git hub projects languish with bad documentation. Actually writing documentation, it seems, is farther down on my todo list than writing a blog post about writing documentation. Part of the problem is that once you start getting serious about documenting it appears that everyone has different ideas of the style, scope, and purpose. With every single sample different, finding a consistent thread of what a specific type of documentation is for, becomes an infuriating mess. If you are like me, this turns into mental gridlock as you agonize over how far you go with the details.

Let me paraphrase a joke I once heard: A group of developers were going over all the different formats their new media player would play. They narrowed it down to a list of 13 formats. Staring at the mess they thought to themselves, “Hey, we’re smart people, we should make a new format to overthrow and unify these other formats.” Then they had 14 formats to code to.

I mention that, because I will not be calling out one style of documentation above the rest. No, I will be adding my voice to the din. Just as a forewarning, I have no place telling anyone how documentation should be done. That being said, I will divide the documentation into three segments. The first will be the foundation, the second will be the stories, and the third will be the generated docs. They have been split based on their audience and their goal.

Foundation

I call this the foundation because it will have information pertinent to the entire project and is readable by everybody, from the managers to the developers. The goal here is to be only as technical as we need to be. To use a Heroku project as an example, this area will hold information like what technology is being used, what coding standards should be followed, what certification the app must meet, and any other project wide promises the app will be held to. Much of this paragraph is built off of section five in the book, Software Architecture for Developers. If your project is using MySQL instead of PostgreSQL, that goes here. If your project is being held to five 9s, god help you and that goes here. If  you have a specific task to submit your app for PCI certification, then that goes in the next section but the fact that it must be PCI certified goes here. So what is the next section?

Stories

I love stories. No, seriously, a well written user story is a wonderful thing to behold. I am basing this section off of my experiences with Jira, but I can think of no better place for documentation about what the project should be then right in the Jira stories themselves. These should contain all of the information about specific functionality that has been promised. The arrangement works out perfectly as all the information, including screen mocks can be added to the story. Questions and comments can be added as well to turn it into a living document, recorded for posterity. This should be a boon to QA testers who only have to look in one location to find out all the information on what a task should and should not do.

Code Documentation

While the above described what should happen, the code comments should communicate how. I am not talking about commenting every line of code, that is pointless and prone to error. Your code documentation should be twofold. First is structured comment blocks, ones that can be parsed by documentation generating tools, placed at the beginning of classes and at least on all public API. You can get the private methods to help out maintainers (and yourself) in the future. The next is inline comments, ONLY when there is a need to explicitly call out what you are doing. To use a real life example, to get JSTL referenced correctly in a recent project, I had to add in three lines of what can only be described as code voodoo. I added a comment stating not to remove it carelessly, why it was there, and a link to a page I got the piece of code from.

Conclusion

All told, with these three components there should be a complete picture with very little overlap or duplication. I say should because documentation is a soft skill. If you have bad code then you can get compilation errors, or test failures, or regressions in QA. Bad documentation can take a long while to surface, if they ever do. The side effect of bad documentation can be confusion, inefficiency, and delay that is hard to quantify but easy to feel. So whether it be a grain or a fast food serving worth salt, take this plan into consideration.