DEV Community

Valentin Sawadski (he/him)
Valentin Sawadski (he/him)

Posted on

Not Documented, not Done!

"Not Documented, not Done!" is probably my most used comment in Jira & GitHub as a CTO and engineering leader 🙄

I hate writing it. But at the same time I'm absolutely convinced that documenting tasks results is amongst the most valuable documentation you can write.

Not documenting task results will have many negative consequences. Without Documentation, People not directly involved with the task will not know

  • if the task got finished, aborted, skipped?
  • where to find the results of the tasks?
  • how it relates to other tasks?
  • etc.

All of which is going to be very important to know as the team grows and will be collaborating with many people on multiple tasks at the same time.

It's also going to be a treasure trove of "undocumented behavior" as Repositories can grow to thousands of issues over the years.

Any old bug report, can either be a source of knowledge on what was tried to fix the bug and decisions on why a bug was "not fixed". Or it can just be a "closed" ticket, leaving you puzzled about what happened and wondering if that's somehow related to your current task.

Therefore I recommend everyone to add short comment covering the following whenever they close an Issue

  • What was the outcome?
  • Are there any links to results, documents etc you can add?
  • Are there follow up tasks or open points that are being tracked in separate issues?

Biggest challenge in being "documentation police" is making that team members are not feeling checked up on, or otherwise offended. I usually resolve these tensions in a 1:1, ensuring that this is about the documentation and not about reviewing the quality of work.

Discussion (0)