There’s been much discussion, especially over the last year, about developer documentation: is it important, how important, and in which context.
And while we at Swimm have always known that documentation is important, GitHub’s 2021 State of the Octoverse report answered these questions in no uncertain terms: Yes, developer documentation is important. According to GitHub’s report, developers see about a 50% productivity boost with easy-to-source documentation.
And, while such an overwhelming productivity increase is good enough reason on its own to start prioritizing documentation, the report goes on to indicate that documentation has even greater benefits. The impact of documentation in building trust and creating a strong organizational culture gives it added importance in the context of onboarding new developers and maintaining ongoing internal information flow.
So, all of this leads us to the next logical question: if developer documentation is so important, should we be including it in the Definition of Done (DoD)?
Defining the definition: what is the Definition of Done?
While most dev teams, product managers, and project managers encounter the concept of “done” every day, it’s worth taking a step back and defining what it means in the context of scrum.
The Definition of Done is generally viewed as a shared understanding of what work must be completed for a work unit (user story, sprint, feature) to be considered releasable to customers. Best practice usually translates the DoD to a series of templates or checklists, each relevant for a different work unit.
Why the Definition of Done matters
Having a clearly defined Definition of Done is important for many reasons:
- It provides a baseline for sprint planning. When dev teams know ahead of time what is expected in terms of testing, documentation, and deployments, they can more accurately size backlog items and plan accordingly.
- It avoids repetitive conversation and redefinition. A clear DoD provides a framework for defining the tasks required for each work unit. So, your dev team can focus on innovation and execution rather than definition.
- It reduces the need for rework. A clear DoD limits the risk of misunderstanding and conflict among the dev team and product owners. Once a backlog item is accepted as “done”, the chance that it will need to be reworked is reduced, and required (non-critical) updates can be moved into the backlog.
Who defines the DoD?
Engineering managers are key players in defining “done” because most of what comprises the Definition of Done revolves around technical requirements.
But defining “done” doesn’t happen in a vacuum. It cannot simply focus on building usable software; it must be aligned with the overall organization’s needs, goals, and core values. Therefore establishing a definition of what qualifies as “done” should ideally be a collaborative process among engineering/dev teams, product, QA, and other stakeholders.
Should the Definition of Done include developer documentation?
Here’s the key question: as you’re aligning your organization and developing your Definition of Done, should it include developer documentation?
Even considering the huge advantages of developer documentation, the truth is that most software development organizations will likely not feel they’re ready yet to prioritize developer documentation to include it in the DoD. Understandable, they’re concerned that the investment is just too great, that their devs won’t embrace it, or that it would result in a DoD that is too involved and unworkable – potentially slowing velocity.
But let’s remember that it wasn’t too long ago we were having the same conversation about whether end-to-end testing should be included in the DoD, and exactly the same concerns were raised then. It hasn’t taken long, though, for us to recognize that writing tests sooner rather than later has provided great value and allowed us to make significant quality advances. And as a result, end-to-end testing has become part of the DoD in many if not most companies.
So while many companies don’t yet feel ready to enforce a policy of developer documentation as part of the DoD, I believe that we are definitely moving in that direction. It’s time to start discussing it and considering how to make it efficient, workable, and a value-added investment.
How to make documentation easier
As code documentation becomes easier and an integral part of development workflows, the more likely it will become part of the DoD.
With Swimm’s platform, documentation is easier.
- Create documentation from PRs and commits. Just start with the part of the code you want to document, and you create documentation from your Pull Requests and commits that Swimm automatically creates for you.
- Use Swimm Templates. To help you get started with documentation, use one of Swimm’s templates from our Quick Start Template list. Swimm has created common documentation topics for you to pick from, so you can just pick a template and run.
With the right tools and processes, documentation is a different task at this point. Adopting Continuous Documentation with Swimm’s platform makes documentation less hard, less stressful, and less of a chore.
If you’re using Swimm, including code documentation in the DoD is gonna be your ticket. We invite you to sign up for a free Swimm demo.
Bottom line
In the end, a DoD is all about trust – across your team and your whole organization. And, as it turns out, that’s also one of the major benefits of developer documentation. Two goals, perfectly in sync.
