My take on documentation

I usually like to keep documentation for a project within OneNote due to the fact it’s really simple and easy to use (especially for dragging in attachments and images!), has first class integration with the Office suite and can be easily synced between team members by hosting the OneNote file in SharePoint or Windows Live. Second to that, I like to store relevant documentation alongside the code in source control so it is versioned and it encourages you to keep it up to date because it is “in your face”; this would normally consist of text-based documentation such as Markdown files. Wikis are also a reasonable option.

One of the things I think is often misunderstood about Agile is a perception that if you are doing Agile then you don’t need documentation. My take on it is that you should at any point in time focus on activities that deliver the maximum value. That means that if you are spending time writing superfluous documentation that won’t provide any value then it’s a waste of time. That doesn’t mean that all documentation doesn’t provide value though; on the contrary, documentation is really important. If there is insufficient documentation for an application then how can a support team be expected to support that application? Similarly, a lack of documentation is a problem if someone is completely new to an application and don’t know where to start looking or know any of the important background information behind it. Documentation plays an important role in the maintainability of any solution.

I see documentation of a system as a combination of:

  • The code itself – thus making it important that code is written in such a way that it is as readable as possible and the intent of the code clear, it also means sections of the code that are hard to read / complex / non-standard should be annotated with comments and in the interest of keeping the code as terse and quick to read as possible leaving comments out of the self-explanatory parts of the code. As an extension of this, I only see it as necessary to add xml-doc comments to interfaces that are used across an application and any public classes in a shared library.
  • The tests – the tests should be an expression of your intent on the design of the system and thus should be able to form a part of the documentation of a system.
  • Other appropriate documentation – by appropriate I mean that the format the documentation is in is the most optimal format for the “thing” being documented. For instance, the documentation to specify a report that needs to be created should probably be a sample Excel file of the report (which is going to be a lot easier, more expressive and more understandable than a chunk of text to describe the report).

I also think it’s important to tailor documentation to the audience; the documentation doesn’t provide value unless it’s accessible and understandable to the people that need to read it.


4 Replies to “My take on documentation”

  1. /me agrees

    However, wikis are never a reasonable option. ever.

    Especially really old ones with a terrible markup language that is never updated or cleaned up. (I may be a little bitter about this :p)

    1. Haha, originally I had “wikis are also a good option”, but changed it to “reasonable” for the very reason that I’m not a huge fan of them for the purposes of documentation. They can be used well though, hence me including them.

  2. Have you read “Agile Documentation: A Pattern Guide to Producing Lightweight Documents for Software Projects” by Andreas Rüping? It has some general guidance on producing documentation (when needed).

    My preference for documentation is generally in-your-face in the source code repository (and for Visual Studio, added as a solution item). Developers are going to grab the minimum needed (Get Latest on the Solution file), so that had best include anything they need.

    Wikis, OneNote, separate folders of documentation, etc, are useful during a project, but it’s easy to lose the link, especially for older projects.

    1. No, I haven’t; thanks I’ll take a look.

      I agree re: the best documentation being next to the code. I find Markdown is a really great format because as well as being dead easy to type in, it’s text-based so lends itself nicely to source control.

      Re: Losing the link: I agree with the provision that if you have established a team (or set of teams) with a consistent approach to the other documentation (e.g. at Curtin we had a Shared OneNote with a tab for each project and then a defined set of sub tabs within that; Project Management, Analysis and Design, Implementation and Technical, Support and Testing) then I think that’s less likely to occur.

Leave a Reply

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