Documentation Handoff – The Trap and Tips!

 

Believe it or not, most software projects cannot do without documentation and many of them require significant documentation handoff from initial days.  Project Charter, Requirement Specifications, Architecture Definition, Design Specifications and the likes, in some form or the other, become the essentials in such projects.  This happens even when you follow agile methods.  Some of these are required when you follow agile with geographically distributed teams.  Beware! Documentation handoff can and will become a trap in your project.  You need to be cautious. I am writing this blog post to share some tips on how to optimize documentation efforts.

Understand the purpose of every document.  Some are live documents and the others such as status reports are periodical and short lived.  Ask questions. Why this document? Who are the consumers? What are the expected outcomes? What is the ROI?

 

Set expectations before you see chaos.  When a document is handed over for consumption or knowledge transfer, avoid

      Redlined documents – They need to go back to the authors and the authors need to go through all redlines and accept or reject the changes. 

 

      Documents without version history – Live documents get updated and updated documents come to you every week or the other. Without version history, it is going to be difficult for you to identify what is new or updated as compared to the previous version.   Including a table that provides version history and list of changes or updates in each version helps readers.  Live documents need to have a life – a life that can be traced back to history, and this is not possible when you ignore version control.

 

      Large documents - Documents with hundreds of pages that take several minutes to download? These are large documents that need not be large unless there are compelling reasons.  Find was to break large documents into multiple small documents.  Move generic or common content out of the document or create annexures or separate reference documents.  Why should you embed publicly available content or external content or common reference in a document?

 

      Documents without reviews or approvals – Are you receiving documents before reviews and approvals? Are you expected to read those and create software or other work products? You need to take a step back and politely ask for reviews and approvals.  Else, you will fall into documentation trap!

Sometimes there is a mandate to generate a new document after reading an existing document. Many of us do this – for example, software testers read requirement specification document and write test cases.  Another example is about reading user stories and creating working code.  The key question is whether or not this approach enables communication among the two parties involved.  In spite of these documents, if there is a communication gap, you need to try a different approach.  Face-to-face discussions, video conferencing sessions, white board sessions, etc. play a vital role and improve the overall effectiveness of knowledge transfer.

 

Another interesting point is about ‘live’ documents.   You hear someone saying, ‘That is a live document. We will get updates next week.’   If that is the case, ensure all that you can so that you don’t fall into documentation trap.  Huh? How do you do that?  Read, ask questions, and get answers.  It is not that simple.  Also, be curious to find out when it is going to be ‘end-of-life’ for such documents.   Live documents are not ‘live’ forever. They need to stop growing, stagnate and retire.  Above all, they must create value to someone other than the creator!  When is the last time you saw an up-to-date architecture or design document that was adored and frequently used by maintainers or product support groups?

 

Check if documents contribute to testability.  For example, creating a document that is full of rhetoric does not help. The content in every section or page should correspond to a verification measure or parameter.  Ask yourself. Have you found at least 2 callouts per page in architecture or design document?  Do those callouts lead to architecture or design guidelines? Do those guidelines help you in software verification or refactoring?  If your answer is no, most probably the document you are using is not serving its purpose or providing any return on investment.

Documentation handoff as a standalone activity does not contribute to software development.  It requires several follow-up activities.  These activities are to help you enhance the outcome.  Here are some examples. 

• Facilitate walk-through sessions.

• Encourage collaboration and resolve queries in a timely manner.

• Validate understanding. For example, let the readers present it to subject matter experts.

With all these in place, how do you measure the effectiveness of handoff?  You can measure that by considering the following. 

1. The quantity and quality of questions asked by readers
2. Level of participation or collaboration in walk-through sessions
3. Quality of document handed off and user feedback
4. Quality of the outcome (for example, the next level of work products such as test cases or source code).

Believe it or not, most software projects cannot do without documentation and many of them require significant documentation handoff from initial days.  Beware! Documentation handoff can and will become a trap in your project.  You need to be cautious!