When it comes to developers working on code documentation, there are lots of different angles to take. Some focus on whether it’s necessary at all. Others consider how and when it should be done, what should be included, and how often it should be updated.
Rather than take a deep dive into any of these specific topics, we’re considering developer documenting from a high-level perspective as a good jumping-off point for deeper discussion and planning of your documentation strategy.
WHY do developer documenting at all?
Tackling the question of why we do developer documenting in 2 different ways. First, why we do it (or why we should do it), and then we’ll unpack some common arguments against it.
Documentation is an investment worth making
As we begin our look at the reasons for investing in documentation, we’re using the word investment quite intentionally. There’s no question that producing quality documentation requires an investment of time and resources. But when it’s done right, that investment pays dividends time and time again.
1. Good documentation makes dev teams more productive
GitHub’s 2021 State of the Octoverse report confirmed what we at Swimm have known all along: good documentation increases dev productivity. But even we were surprised by how much. GitHub’s research showed a 50% productivity boost for developers with easy-to-source documentation.
A 50% productivity increase is probably a good enough argument all on its own, but just in case, we’ll add a few more.
2. Documentation contributes to building strong team cultures
GitHub’s report went on to highlight the importance of good information flow to building trust and promoting developer satisfaction. Particularly in our current reality of geographically dispersed teams and remote working environments, documentation plays a critical role in ensuring knowledge sharing among team members – both current and future.
3. Code documentation is essential for onboarding new developers
In research conducted by Harvard Business School, executives acknowledged that their companies could do better in onboarding new employees – even pre-pandemic when things were rolling right along. This perspective is confirmed by Gallup research of employees themselves, which found that only 12% of employees strongly agree that their organization does a great job of onboarding new employees.
For developers, an important part of the onboarding process includes a tour of the existing codebase, an overview of system architecture, and an introduction to team coding practices and conventions. Ensuring that this education happened every time and with consistent quality was difficult enough when it took place face-to-face, but the added complication of remote onboarding makes it even more difficult.
Rich, self-paced onboarding experiences that include walkthroughs of the codebase and examples of existing code meet the developer onboarding challenge and then some. Though it will never take the place of personal mentoring and team interaction, properly designed documentation eases developer onboarding and supports empowered developers who can quickly make positive contributions to the team.
With Swimm Playlists, you can walk your new developers step-by-step through the codebase – including markdown files, code snippets, videos, images, and links – just as if you were sitting next to them!
This is part of a series of articles about code documentation.
Debunking the myths about documentation
Most developers will tell you that documenting code is not their favorite part of the job. As a result, they’ve never had a problem coming up with reasons not to document their code. These reasons have become so ingrained and widespread that they’ve taken on the qualities of myth.
So debunking the top 3:
Myth #1: Good code documents itself
Wouldn’t it be nice if this were true.
While exceptionally well-written code might speak for itself in terms of what it does, code documentation should really focus on the how and the why: How does the code do what it was designed to do? And, of all the available options for accomplishing this task, why did you choose to code it this way?
Fast forward to one month after you finish coding a feature: Will you really remember the answers to these questions when it’s time to fix a bug or add functionality?
Even the best-written code won’t answer these questions, so it’s important that the documentation does.
Myth #2: There’s just no time
Lack of time assuredly has a grain of truth to it if there’s no organizational buy-in to the value of documentation. Fifty percent productivity boost for devs with good documentation, in our mind, is incentive enough to lead the charge towards getting organizational buy-in to code documentation.
Myth #3: Documentation is not customer-facing, so it’s not part of the product
As long as SaaS is the standard in software delivery and software development remains dynamic, your product is much more than the code. Customers expect features to be shipped faster, with higher stability and fewer bugs. So, if internal documentation leads to the next release coming faster and more efficiently, our feeling is that it’s part of the product.
And even though code documentation is not intended to be customer-facing, it’s actually a great time saver for the rest of your team.
WHO is the documentation for?
This is the first question you should ask yourself when you start writing any piece of documentation, and the answer can differ depending on the situation.
- Current and future developers who will be called upon to update and add to your code (whether they’re new devs being onboarded or existing team members taking on new tasks)
- The future you when you’re asked to squash bugs and add functionality to your code after you’ve put it down for a while
- Technical writers, UX designers, researchers, and writers, or product managers who will write customer-facing documentation for your features
- Customer support team members and sales engineers who need to answer customer and potential customer questions confidently and accurately
All of these internal consumers; many stakeholders, indeed.
Learn more: read our guide on Documentation in Agile.
WHAT should the documentation include?
A good place to start is thinking about the things that a new developer on your team would need to get up to speed:
- Walkthrough documentation (a guided tour of the codebase) with markdown documents that use code snippets as demonstrations
- Explanations of recurring code patterns, algorithms, and interactions between parts of the code
- Descriptions about how a block of code accomplishes its function
- Explanations of why a particular option was chosen to solve a specific challenge
- Notes about bugs and how they were solved
- Changes to the code and why you made them.
WHERE should developer documentation be maintained?
Maintain your documentation in the repository alongside the code. In fact, it’s best practice to treat your documentation as part of the code itself, using the same source control and versioning.
Of course, the best documentation in the world isn’t going to help if no one can find it (or even knows it exists). Make sure it’s properly indexed and fully searchable. Link to it from Slack channels or export the most recent version to any knowledge-sharing platforms your company uses (such as Confluence or Notion).
And to truly make the most of your code documentation, make sure it’s visible and accessible right when you need it: while you’re working on the part of the code it relates to. Swimm’s IDE plugins make it particularly easy to do just that.
Related content: read our guide on Coding Diagrams.
WHEN should developer documenting take place?
It’s perfectly intuitive to recommend writing documentation as you are coding or immediately after you finish. This is when the knowledge is fresh and best – flowing most easily into words.
Another best practice is to start writing even before you start coding with an outline of requirements and specifications for the code you are about to produce. You can easily identify gaps and create a clear path forward.
HOW should developer documenting happen?
There is certainly no shortage of best practices for developers working on documentation:
- Write just enough: Find the right balance between under- and over-documentation. Keep repetition to a minimum; instead, cross-link your documentation so that information is single-sourced and easier to maintain.
- Use glossaries: Keep your documentation streamlined by defining terms and using them as needed. And don’t forget to link to the appropriate glossary entries when you use the terms you’ve defined!
- Make it a collaborative effort: Get input from your peers and other stakeholders. Your peers are some of the main consumers of your documentation, and no one knows better what they need than they do!
- Consider the medium: Great documentation consists of more than endless text. Consider the type of documentation that will get your point across best: annotated images and screenshots, code snippets, links to relevant outside articles, videos etc.
- Keep it up to date: The most important best practice of all! In order for your documentation to have relevance and credibility, it needs to be regularly (continuously) maintained. Documentation that doesn’t change along with the code can cause reader frustration and errors.
Bottom line
Code documentation is an investment that pays for itself over and over again. At the same time, we should make wise use of our investment resources by carefully considering the aspects of how, why, and for whom we are documenting in order to create and execute a comprehensive documentation plan.
Swimm makes it easier for developers: with code-coupled editing, auto-sync, IDE integrations, Swimm keeps your documentation always up to date… and delivers it right where and when you need it. Become a part of Swimm’s growing developer community, and check out our free Swimm demo.
