Technical User Standards Design Experience Interface Documentation

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.


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?


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.


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.


  1. Jesse Altman says:

    Documentation just isn’t as fun as writing the code! I like this article, but I have to say I disagree on your section about Code Documentation. Structured code blocks that can be used to generate documentation (think JavaDocs) make perfect sense to me, but inline comments or just huge comment blocks at the top of each class with some extraneous info tend to just waste space and time in my opinion. I am a huge fan of self-documenting code. It will never become stale and for the most part, should eliminate the need for 95% of inline comments. Either way, good article! This is a topic that doesn’t get discussed enough.

    • Bob Roberts says:

      Hmm, I tried to make the point that the inline comments were just for times when self documentation just wasn’t going to happen. I agree that most times inline comments should be unnecessary. As for the big class wide blocks, I was envisioning small, concise blocks but that just goes to show how much of this is based on assumptions.

Leave a Reply

Your email address will not be published. Required fields are marked *