To Document or not to Document: Stop fighting documentation by integrating it.

In an earlier post I talked about the great agile/waterfall documentation debate.  One method, waterfall, extensively documents everything while agile, another method, consciously cuts down documentation to the minimum amount that is viable.  While both have good points, an ideal system would incorporate documentation naturally into the process, where the team does not even realize that they are documenting as they go.  A classic example of this is the automated test.  By looking at the test and its results, you should be able to gather most the necessary information about the test.  In this article, I will demonstrate some other examples of how to do this in other parts of a software development life cycle.  This will of course not be a comprehensive list.  Rather, this is a place to start discussion and ideas of how to integrate documentation naturally.

One very simple method to create a natural trail is to use meetings and agendas.  Meetings are a place where requirements, changes, baselines, and other major decisions can be decided; certainly prime material to document.  Sometimes these are not captured very well though.  Have you ever walked out of a meeting feeling great, then arrive at your desk and realize 'Now what am I supposed to do'?  Next time you have a meeting:

•  assign someone to be the 'timekeeper', 
• have him create and/or distribute an agenda
•  give him the responsibility of capturing meeting outcomes

If the timekeeper keeps an agenda and writes out important outcomes and decisions, a trail is naturally created  that captures documentation information.  It will also help you avoid the 'now what?' issue.  There are some barriers to this though.  To encourage free conversation, guidelines will need to be created to define idea sharing and brainstorming from final decisions to document.  Otherwise idea generation will be impaired and non-binding decisions and ideas will be captured in the formal documentation.  It may be difficult as well to naturally add certain assumptions and knowledge that everyone already knows before the meeting, and therefore won't be discussed and captured during discussion.

In our wonderful high technology world, there are some very great software tools that can be used to document a whole variety of project elements.  While there are dozens of choices that range from free, localized editions to giant enterprise SaaS implementations, I'm only going to mention AtTask and Jira here.  In AtTask you automatically capture update conversations between collaborators, can attach documents, pictures and other items, and know at any time the status and team members of a given task or project, along with a host of other options.  Jira actually started out as mainly bug-tracking software but is a very flexible platform with tools for updating, sharing, and discussing project elements.  There are many great software tools that automatically create a great trail but it is important to remember that they are only tools.  They won't capture face to face conversations, for example, and if you want to capture specific information, you will need to set those guidelines down in your organization.  For instance, QA may require that issues come with a 'steps to reproduce' list and maybe screenshots or system information.

I would also like to mention lessons learned as part of integrating documentation.  Lessons learned is one of those things that gets forgotten a lot at the end of a project.  This is partially due to the prevalent yet false idea that lessons learned should be administered only at the end, and not integrated into, a project or phase.  Agile surprisingly, has made some gains in integration by using daily standup reporting and sprint retrospective, essentially daily, and sprint lessons learned.  Whatever the method used, integration of lessons learned into the natural process of carrying out the project is likely the most helpful improvement of all of these. 

These are some great practices that will help your organization have a smoother process for documentation.  This should also foster ideas and discussion on tools and techniques.  One thing that we have not addressed yet is best practices and rules, which should certainly be developed at some time.  Please feel free to share your ideas and stay tuned.