You need a wee bit more documentation
To help new developers hit the ground running, and to keep your entire dev team aligned, you need some stable, lightweight documentation.
- Clearly state your ways of working, especially how developers collaborate amongst themselves and the team, your environments and access control and your project metrics.
- Write a sharp README file for each code repository that helps developers start contributing to that codebase in a short time.
- Limit your documentation efforts to solve real problems. Where possible, automate documentation using modern tools, so everything's always up-to-date.
Earlier in this series, I mentioned your team will need a handbook. We’ve also discussed the audit trails you should create while in the flow of your work. If you look hard, you’ll notice that the goal still isn’t to create “comprehensive documentation”. The idea is to create enough “sensible documentation” that helps make communication effective.
Visualising the structure of the team handbook
Referring to the structure of the handbook, I want to zoom into a very specific section. This relates to developer documentation. Hold on right there. I’m sure you’re rolling your eyes as I say this, so let me set you at ease.
You need to write documentation - more than what you may do today, but less than how much you fear I’ll suggest.
The goal I want to achieve is straightforward. How can you document your codebase in a way that any engineer can join your team and start contributing from day one? Before we get into the specifics of that, I’d like to share five principles that I’ve followed on my projects.
Documentation for the sake of documentation is problematic and wasteful. Our documents should serve a purpose. As a corollary, when a document ceases to serve its purpose, there’s no point maintaining it.
We prefer dynamic, automated documentation for things that change frequently. People should spend their time documenting only things that are stable.
The lighter the documentation, the easier it is to consume and iteratively improve. Anyone writing documents needs to practice brevity as a skill.
People consume documentation in specific contexts. This makes the location of the document just as important as its content. Sweat those little details.
A single outdated document can shatter a team’s faith in documentation. This means that we should not only budget for the cost of creating documentation, but also that of maintaining it.
If you’ve been practising agile for some years, you’ll appreciate the sentiment of the above principles. As Scott Wambler says,
“With high-quality source code and a test suite to back it up, you need a lot less system documentation.”
So let’s get into the bare essentials that you should cover as part of the internal developer documentation for your project.
Your ways of working
When a developer first joins your team, they’re itching to start strongly. You want to minimise the guesswork they have to do. At a later point, we’ll talk about onboarding strategies in particular, but in terms of documentation, here are questions you should answer up front, in writing.
How do you collaborate as a team?
Do you pair-program by default or do you work independently and do code reviews after? What’s the process for code reviews? When teams pair-program, they like to have some consistency in how everyone sets up their laptops. Do you have any guidelines for that?
How do standups, story kick-offs, desk checks and other practices work? Even within the same company, especially within consulting firms (like mine) there are variations in how teams conduct the same practices - so it’s best not to leave things to guesswork.
What are the different environments you have on the project?
Different teams have different environments. For example, development, QA, UAT, staging and production environments. Each of these environments will have different permissions and credentials, access control and deployment protocols. If they need to set up access, then the instructions should be crystal clear.
Your developers will also need to know about what level of analysis, monitoring and alerts you have set up so you can learn about the health of the system and fix issues when necessary.
How do you track project metrics?
It’s tough to improve things we don’t measure. Teams use tools such as LinearB, SonarQube or Polaris to assess themselves on several parameters, including code quality, four key metrics, non-functional requirements such as security, maintainability, reliability, performance and a lot else. Even if your new developers don’t have experience with all your tooling, it helps to give them a lay of the land right at the start.
Codebase README files
Depending on the size of your project, you’ll have one or more repositories and each of them needs minimal documentation. We don’t want to document things that will change frequently, for example, the code itself. Your code should self document through:
using design patterns;
eliminating code smells;
and comprehensive unit tests.
You want to document the stable stuff - the things you don’t want to say to each developer repeatedly. A great place to do this is right in the codebase, in a good, old README file, at the top level of your project folder. This is usually the first file people see on a project, so there’s a big incentive to make it useful. And there are tons of resources to guide you to do this well. I particularly like Kira’s, a.k.a hackergrrl’s “Art of README”.
Here are a few sections you should include.
The project title and description. Goes without saying, right? If you have a say in the project's name, please keep it intuitive. If not, maybe explain where the name came from? You also want to explain what the software does.
Installation and usage. A new developer will want to install and use the software to learn how it works. Simple step-by-step install instructions are very helpful. Be sure to list dependencies, if any. You also want to show them how you run and use the software. If a video helps here, link it in? List down terminal commands step by step. If developers need to specify some environment variables, list those down as well. Be careful not to list privileged information here, though. Use other means to share project secrets.
Visuals and code overview. If you have a high level architecture diagram or a dependency graph or UML diagram, link it in here. Be as brief as you can when explaining the code. Ideally, a picture should speak a thousand words and you may get away with a few bullet points to supplement the images.
Creating your readme using readme.so
In addition, depending on the context, you may need to add contribution and support info, links to API specs, the ADR folder and other details. If you haven’t written a README before, fear not. There are two tools that’ll help you generate these files with the complete markdown syntax. All you need to do is pick the sections you need in your file.
Many sections of the README file will remain stable for a long time. By cross-linking to other artefacts, such as API specs, you can limit the number of updates you need to make to this file. A good practice is to set up a team reminder to review this file quarterly.
If you’re doing any more manual work creating technical documentation, you may overdo it. As always, it’s a cost-benefit exercise, so I won’t dissuade you from doing it. “Write the Docs” is a great community to learn from, if you want to get better at documenting stuff. Just remember that code documentation can get out of date quickly. Fortunately, there are some new tools on the horizon that can simplify creating or consuming documentation. Here are some tools that could be useful in your context.
CodeSee auto-generates interactive codebase diagrams for Go, Java, Python, JavaScript and TypeScript codebases. This can help speed up people’s understanding of the codebase and also the impact of the changes they’re making. The maps can also help simplify the code review process.
StepSize allows developers to document tech debt inline with the code they’re looking at right then. Your team has a clear incentive to ensure you’re tracking tech debt, especially if it’s so easy to do from within the IDE.
Glean helps tie together multiple information sources on your project through a universal search. That way, if you’ve got multiple tools like Jira, Confluence, GitHub etc, you can minimise the number of clicks it takes to get to the right piece of information.
I’m not endorsing any of these tools. You can try all these tools for free if they seem like the thing you need. If I had to leave you with some parting advice, it’ll be this. The best documentation is the one that scratches a real itch. Focus your documentation efforts on solving genuine problems and don’t overdo it!