No Document? Here is How TDDD Save Your Life
Why No Document?
Documents are important. Everybody knows. Then why we have such numbers of missing documents?
Engineers are lazy by nature. They try to find the optimal route to complete their work. Their primary focus is to deliver the value of the product to the customer. Naturally, minimal documentation is compiled.
Documentation First
Typical project response in supportive measure. Somebody says “hey, we should have more documents”. Project members start compiling documents. As a result, a good amount of the areas are covered by the new documents. However, this approach is not perfect.
First, we lose the context of the design at the time we write the docs. “Hey, do you know why this design look like this?” “Ah, that was designed by Smith who left the project”. This is the typical example of the loss of context. Or even if you are the original designer, are you able to remember the design decision you made one year ago?
Second, the post-documentation process cannot cover all the topics you need to document. Once the intensive documentation activity is done, the project continues as usual. Then you will suddenly find that some of the design is missing. Then you need to go back to the documentation activity again. We can say that we need to add more documents as we find. But it is still continuous pain.
As time passed from the time it designed, documentation becomes much harder. Why not we design a “pre-documentation” process than the “post-documentation” process.
Ticket Driven Design Doc
Here Ticket Driven Design Doc (TDDD) helps your life. I have been working on management in several different projects and teams and found TDDD promotes pre-documentation culture to the team.
I assume that you are using some ticketing system to handle the development process. You can put “documentation” and “documentation review” as part of the workflow. Here is the example workflow in a typical story-based agile project:
Every development ticket has documentation as part of the process. This forces engineers to make a document for any changes. Wait, putting documentation as part of the workflow? It sounds obvious. Whats’ the point? Well, we have another key driver for TDDD.
You make a document based on the ticket number. Here is the example:
This might remind you of RFCs. Yes basically, we leverage the same idea. Ticket number based document have some characteristics:
Documentation Status and Authenticity Clarified
When you use a collaborative documentation tool (like Confluence), you will find some documents whose status is unclear. The document might be draft, might not be up to date, might be reviewed by anybody, or might be even just a private note and not official.
Putting ticket number will clarify the status of the documentation. It also clarifies that who reviewed the document and who approved.
Clear Mapping of Development and the Doc
Since the ticket number is clarified, mapping of the development is clear for everybody. This will allow project manager to see the status of the documentation. If feature development is undergoing with no documentation, the project manager can ask engineers to write a doc, and ask them to have the review.
Change Part Clarified
As development activity and doc is mapped, the document clarifies the changes. If you keep updating the master document, the reviewer of the document might be unclear which part is already developed and which part is the change we design now. Ticket number based document forces engineers to write the changes. This will help document reviewers in general. This will also help QA to understand since they generally understand the changes.
Documents Linked
We can link the document with some relationship like RFCs. If you are incrementing the changes, you can link the documents as “Update”. If you are replacing the old feature with a new one, you can link it as “Obsolete”. You can clarify what kind of “changes” you are describing in the doc by the linkage.
Readers of the documents can also be aware of any update thanks to the document link.
Mitigating Weakness of TDDD
TDDD is not perfect. Since TDDD is focusing on the changes, it’s not good at updating the master documents. Let’s imagine that we have API specification. TDDD does NOT guarantee that API spec to be updated.
As TDDD is focusing on the change, it’s weak for maintaining master. We need strategy to mitigate the weakness. Some automated documentation tools, like Doxygen or Swagger, can be one of the solutions.
TDDD Promote Pre-Document Culture
As I clarified the above, TDDD is not a perfect solution. However, TDDD promotes pre-documentation culture to the team which is the fundamentals of the development process. TDDD grantees also guarantee the documents’ authenticity.
I had several successful experience with this approach in past few small team. Now I am promoting similar approach to several new activities. Hopefully I can provide more updates by a post in the near future.
