A question came across the Vets Who Code community where they asked about "where does documentation come in the dev process?" They further explained that folks on their team believe that documentation is "anti-agile" and boy I have opinions.
Where does Documentation come into the Dev Process
Different forms of documentation fall into different stages of the dev process for me. Though I probably have a looser definition of what documentation is than some. This is just my ideal workflow
Ticket
I think a general ticket should be started by someone who's not going to take on the work. This is the requirement for building of a system. It's a piece of documentation that will tell you who the owner is.
Design
Depending on complexity of that ticket you may need to get multiple eyes on mapping out a solution. This piece of documentation can be a motivating factor to get everyone's goals aligned and get general expectations of the products.
Epic/User Stories
Again depending on complexity build out general technical user stories that folks should be able to pick up and with the context of the design should be able to execute on (it's okay if there are questions).
Tasks/sub-tasks/User Stories
I'll document all the work that I'm doing (pretty much my standup updates) get turned into sub tasks or comments on my user story. This way, if folks aren't paying attention in standup, which I found often is the case they can check progress via tickets.
Code comments
I think if something doesn't fit the general pattern comment it. If there are side effects that could possibly be unexpected, comment it.
Function/Variable naming
Make them explicit, it's a form of documentation
PR Reviews
Are a type of documentation. When using Git Blame you can find the PR that the piece of code comes from. I've gone back to those PRs to find out the point of the feature.
Confluence/Wikis
Document workflows and full features that folks need to know about to be able to complete certain tasks. These are guides that can be shareable between teams. They're good for onboarding. They also reduce fragility of a team, so folks can feel like they can take time off.
API Docs
If you're building an API that's meant to be consumed by anyone, please set these up for the love of Bob.
Anti-Agile Sentiment
I've heard this anti-agile sentiment before. The challenge here is that they're possibly mis-using the concept.
They could be saying that it's anti-agile because it could feel like waterfall. I've had push back when I do design docs because folks believe that's waterfall. It could be a waterfall practice if it was meant to be a source of truth as opposed to a general plan.
The second reason I've heard folks misuse the "anti-agile" concept is that they believe docs slow teams down. I disagree with the concept that agile means fast. I've always interpreted it as agile means flexible.
In the end though when it comes to documentation I have yet to see a verbal argument win. What I do is document as much as possible. You create the trail of breadcrumbs and people find it and are grateful. Sometimes I'll get told that I'm special and like to document. But honestly if you just have it as a part of your workflow folks eventually join, because you're providing value and people will see it.
Warning it may get frustrating because you're the only one doing it. Or maybe folks will tell you to stop. In any case, documentation is good for you and will help you grow irregardless. A team agreement doesn't have to block you from providing value.
Top comments (0)