75.4% of new software developers say that bad documentation is their #1 blocker at work. During the pandemic and remote work, software developer teams have reported 3x slowdown in collaboration due to lack of documentation and challenges in collaboration. So what’s going on? Is it so hard to write good and reliable documentation? Well, yes it is.
And there are 2 main reasons to that:
- Writing for other developers is hard.
- Updating documentation when code changes daily is a lot of work.
This article was originally posted at: https://quod.ai/post/how-to-keep-developer-documentation-up-to-date-in-a-ci-cd-world
What’s good documentation anyway?
To understand what makes documentation good, we must first talk about the goal of documentation. Why do we need documentation in the first place?
Good documentation answers questions from other developers
In order to evolve an existing codebase, a developer should understand the existing code. As developers, we’re constantly asking questions about our codebase to better understand and evolve it.
In a research case study, Google collected questions that their own software engineers asked when coding. They categorized all of those questions into 5 categories:
- How (example code): How do I use X API? How do I implement feature Y?
- What (reading specific code): What does this script do? What’s the name of the enumeration?
- Where (code localization): Where is the code to do X? Where do we configure environment variables for Y?
- Why (determine impact): Why did my change not work?
- Who and when (metadata): Who edited this code and when? Who can help review this code?
In normal times, working at the office, you could just tap on your co-workers shoulders to get your answer (even though he may not like being interrupted). Now, with Slack ping pongs and Zoom overload, getting answers is a lot more work.
Obviously, it’s not easy to communicate online. But for developers, discussions require a lot of technical context and complex technical situations. IRL whiteboards are super helpful… However, digital whiteboards… not so much.
So how can we collaborate productively on code without face to face or whiteboards?
The attributes of good documentation
In the context of information systems, documentation is organized information. And when it comes to information, there are 11 criterias that define how good it is. We’re going to go through all those criterias but essentially, documentation should:
- Be easy to find.
- Be easy to read/write and update.
- Be up to date and simple.
- Offer the whole context.
Usability
The criterias for usability of documentation relate to how easy it is to read and write (and update) documentation.
- Relevant: documentation should show what’s important to its reader. For devs, documentation should help make technical decisions.
- Simple: documentation should be easy to read and not go into details that are not needed.
- Economical: documentation should be easy to write and update.
- Flexible: documentation should be consumable by different people in your team with different goals. For example a QA could look up the password reset feature from a BDD perspective, while Frontend and Backend can look up its implementation.
Delivery
The criterias for delivery have to do with the how and when. How the documentation is read and found.
- Accessible: documentation should be available when you need it, in the format you need it. For example: in the IDE as I call a function; in Github when I search for code; or in Slack when I ask a question to my team.
- Timely: documentation should show up when we need it. Not a week later when the PR is ready to be reviewed.
Quality
Quality of documentation reflects how good the decisions are, after documentation is read. A developer could make bad decisions if the documentation is out of date, incorrect or lacks important context (and he is unaware of those issues).
- Accurate: documentation shouldn’t have any errors. Duh. But easier said than done.
- Complete: documentation should explain code impact and full context. For example, imagine microservice A saves users in the users table and microservice B also writes to the same users table. If the documentation for A fails to mention B, then it wouldn’t be complete.
- Reliable: documentation should rely on data and facts rather than opinions or mis-collected data.
Practical tips to keep documentation up to date in a CI/CD world
I once heard an enterprise software architect say at a public talk “Don’t bother updating documentation. By the time you’re done the code will have changed.”
Today, we are expected to release faster than ever: weekly, daily … and sometimes even hourly. Documentation is hard to maintain. However, we can make our job easier by following the principles of good documentation:
- Be easy to find.
- Be easy to read/write and update.
- Be up to date and simple.
- Offer the whole context.
Avoid writing code comments
A few years ago, my CEO asked me if our departing software engineer had documented his code with comments. I answered: “I hope not”. He laughed… but he didn’t realize I wasn’t joking.
A comment is a failure to express yourself in code. If you fail, then write a comment; but try not to fail.
- Uncle Bob
We sometimes tend to write comments to explain the behavior in our code instead of writing good code. We expect code comments to explain the expected behavior of the app. For example, a developer on your team may ask: “When does the user have access to premium features?”
Bad:
// Checks whether the user has access to premium features
if (user.subscriptionPlan == 'premium'
&& user.billing.lastPaid 30
|| user.daysLeftInTrial < 30)
Instead try:
if (user.hasPremiumFeatures()) {
Write code that’s self documenting. Robert C. Martin (aka Uncle Bob) has dedicated a whole chapter about comments in his book Clean Code. Check out Chapter 4. He has fantastic examples of good and bad comments.
Essentially, there are 3 types of code comments:
- Redundant/noisy: just remove it.
- Explanatory/summary: refactor the code.
- Useful: explains the why - keep it.
Keep your documentation light… or just delete it
Have you ever read documentation that you knew was out of date? But you knew some parts were correct? Stale documentation can be as useless as no documentation because you don’t know which parts you can rely on. Or worse, you could rely on it thinking it’s up to date when it isn’t.
So before you start writing documentation, ask yourself:
- Who’s going to read it? What questions will they be asking?
- How often will I need to update it?
Make documentation easy to find
One of the reasons documentation gets stale is because it doesn’t get used often. It doesn’t get used, because it’s hard to search (*cough cough* Confluence).
Organize information so that it’s easy to find when others need it. Here are some practical tips:
- Add README.md in sub folders of your repos to explain specific modules or concepts.
- Link your tickets/issues in your documentation. Use hashtags and keywords to make it easy to search.
- Move important information from your Slack to your README.
- Organize your documentation into folders that are consistent and logical:
- For a standard README table of content, we recommend our ultimate README as a way to organize your processes.
- Use a nomenclature that’s easy to follow and think about. For example: README, LICENSE, etc.
- Organize your Confluence documentation into folders that reflect your features (example: user, billing, authentication, etc.). Use the same folder hierarchy consistent with how your code is organized.
Keep documentation close to code
One of the biggest reasons for obsolete documentation is that it’s far from source code. As discussed above, documentation should be easy to write and update.
Real code examples
The most searched documentation at Google is real code examples. For example: How do I use the billing API? Is there example code that does this?
You could write a paragraph about the endpoint URL and each of its parameters, the HTTP verbs, expected parameters… Or, you could just write an example usage of your API as part of a demo. Or better yet...
Write tests
Tests are a great way to document the expectation of your users. For example: “When does a user get locked out of his account?”
describe("User login", function() {
it("should lock out", function() {
login(“jdoe", "wrongpassword");
login(“jdoe", "wrongpassword");
login(“jdoe", "wrongpassword");
expect(statusMessage).toBe("You’ve been locked out of your account");
});
});
Running your tests frequently (or using CI/CD) will force you to update your tests as documentation when the behavior of the app changes.
Code tutorials with git message and merge commits
Another way to document is to link your git messages, with your issue tracker and pull requests.
This can help answer questions like: How do I add a new database entity into our app? How should I name the API routes? Which files do I need to edit?
Source: add Note API
If someone has implemented a similar feature before, one great starting point is to get inspired from that commit. It’s an example implementation to build on.
Automate with tools and scripts
Turn documentation (processes, rules) into apps and scripts. Automation removes ambiguity and sets up (very) clear step by step instructions.
For example, instead of writing in prose “how to export users from the database in CSV” or “how to build and deploy the app”, why not write a script or a program to do it? Very much like testing, automation (if used frequently) forces you to update your scripts when behavior of the app or process changes.
Writing documentation can be a great way to support developers on your team. However, documentation is a time investment by the entire team. Your team needs to write, update and organize your documentation so that every developer on the team can benefit for effective and productive collaboration.
But ... What if you could spend less time documenting and organizing? Yet, still be able to answer questions from your fellow developers?
Use AI for easy and simple documentation
At Quod AI, our goal is to help developers find answers in the smartest way. Our platform turns source code repositories into documentation using Deep Learning and NLP.
There is only one step to get your documentation: submit your Git repo URL. That’s it. Our AI models take care of the rest.
We’ve submitted Winds, a gorgeous open source podcast and RSS feed app. Using Quod AI as auto generated documentation, we’re going to answer questions based on Google’s case study.
Example code of how use the articles API
How do I retrieve an article using the API? To answer this, let's search: retrieve article api test.
The first result is a test that shows a test to retrieve an article from the articles API.
Exploring and reading how articles work
What is an article? What can a user do with an article? To answer this, let’s search: article.
Not only did I learn about that an article can be pinned, I also learned from the suggested search that parsing article was an important feature of article
Sharing authentication code
How do you prevent unauthorized access? How do you reset a user password? How do we prevent unauthorized access?
In most applications, authentication is spread out around in many files due to its complexity. The Winds app is no different.
Sharing one snippet of code is not enough. That’s why Quod AI supports the concepts of collections. Collections are like a YouTube playlist of code snippets (without the music and copyright infringement).
I created the authentication collection in 5 minute. All I had to do was to find and collect snippets. Yet my documentation for authentication is fairly comprehensive because the code is automatically augmented with questions and tags.
Sometimes, code is not enough and you need to contextualize the code. In that situation, you can simply comment on the code. When sharing a collection, your team can read the code with the added context of your comment.
Sharing environment configuration
How do I configure the database for Winds? Which port is Redis using?
Winds has most of its environment configuration centralized into one file. But for ease of readability, I created a collection to show the dev, test and production configurations. Check out how to configure Winds’ external dependencies.
Trace code history for Podcast schema
“Podcast” is one of the most important concepts of Winds. Naturally, it’s one of the most viewed code files. Who’s the best person to review this code? Who can help me understand this code?
To answer this, we can go directly to models/podcast.js in Quod AI’s smart Code Browser. The automatic context tab gives us information about who are the key contributors to a specific snippet.
What were the last changes and which ones were impactful? Quod AI can answer this automatically as it resurfaces the latest commits with an impact score. A low impact commit is a commit that reformats the code and doesn’t change the behavior of the code for example.
That’s it! Documentation was and still is an essential part of software development. It’s just changing.
Quod AI is code search and navigation on steroids. We turn code into documentation that developers actually use. Do follow us on twitter @quod_ai for updates on our product and DEVs community content. Check our app at: beta.quod.ai
Oldest comments (0)