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.
- The quantity and quality of questions asked by readers
- Level of participation or collaboration in walk-through sessions
- Quality of document handed off and user feedback
- Quality of the outcome (for example, the next level of work products such as test cases or source code).
