How much we care about knowledge transfer

I think this is the most obvious point, but also not one that’s very specific to a readme file. There are many other tools for knowledge transfer like company wikis, emails and Slack. Still the presence and content of a readme can tell you how much your team cares about knowledge transfer. For new team members the readme might be the first touchpoint with your documentation.

About clarity and clearness

In most cases readme files are kicked off just out of habit and filled with details mostly relevant at the time of creation of a repo, project or module. And in many cases it stays like this. In essence what this tells us is: I created this because it’s expected of me, but I don’t really see the value in evolving it. As you grow more senior in your profession you should look out for places like those, as it can denote a bad habit. Following this habit is contagious as it tells your peers: It’s OK to leave it like this, avoid it or make clear decisions about it.

In this case the readme can tell us how much your team values clear decisions and a clean environment that encourages care about the code base.

How we’re able to reach beyond the daily work

If you save on documentation, chances are that you put the burden onto somebody else afterwards and manyfold. That sounds obvious, but it still happens. We’re developers, after all, we’re good at writing code, but for writing good documentation and even to know that documentation is needed, a set of very different skills is required, like empathy and being able to obtain a meta-perspective on the process of research, entering a new team and even navigating the social space in and around the team. It can be pretty high-level!

So the readme can tell us how much you as a team are able to transcend the daily coding practice, take a step back and see what new hires need to get started smoothly.

Who is doing what and how often

I could have named this chapter “git blame & log” and that’s exactly what I mean literally here. It might be a good idea to try it out once, there’d be a lot to see:

• How frequent are the changes? This tells us how much love the readme is receiving, but still on a superficial level.
• What changes often? Chapters having good quality, being relevant for the reader and not changing much anymore over time might signal they’re pretty set and mature, so no need to do something there. But if those factors are absent it calls for more clarity about what to do with them.
• Who is introducing the changes? This points us to how distributed the responsibility is. So if a readme file is well-maintained, but only (or mostly) one person is taking care, this might show that the practice is not very well aligned. Could also be this person is well-meaning but not very effective in communicating and spreading good practices (which is OK, we all have strengths and weaknesses). But nonetheless, the person is the single point of failure: when they leave, so does the practice.
• Who is introducing changes where? Now this can be quite interesting as well. While the point above was “communication skills” in general (or the lack thereof), this is more about knowledge transfer. In essence, different people adding and changing stuff all over the place points towards a well-established knowledge transfer. And I think it’s generally agreed upon that it’s a good thing. The “single point of failure” argument applies here as well.
• Is a new team member adding things during onboarding? And if yes, is it helpful? This can give you hints about a new member’s assertive attitude. But beyond that, if they add a lot that means that a lot was missing, too. Good to know retrospectively.
• Are you removing stuff? Removing stuff is pretty serious: you actively remove something out of the immediate field of perception (even though it’s still in the git history). If it’s not a stupid move, this points towards somebody being deliberate about reducing complexity and outdated content, improving clarity, or more generally, having made a conscious decision about something.

How much we care about alignment

As much as it’s true that everyone has their own style of doing things, a very important measure of how mature a team is is its ability to align effectively in the face of increasing complexity. And if a readme file is not supposed to be a place where people can randomly dump stuff in, it can be a place where decisions manifest in the form of clear instructions and guidelines. So indeed, a readme file can potentially give you a picture of how good the alignment level of your team is.

Considerations

Looking back writing all this I have to admit that the area this topic touches is pretty big. It goes beyond a file, it’s more than about documentation, it even touches team communication and, surprisingly, only very little technical details. I didn’t plan for it to turn out like this, but the interesting thing is that whatever can be learnt here can be applied in a lot of fields like team leadership, communication and alongside professional growth, as well.

Concluding all that, what takeaways can we drive home now?

• Why the readme file? Besides code comments, the readme is the most accessible storage space for documentation and obvious point to start with (although this often isn’t reflected in the habits); I’d even go so far that proposals can be handed in in the form of pull requests with changes on the readme file everyone can comment on, where being merged counts as “agreed upon”.
• Representativeness: use your readme file as source of truth, and if it doesn’t reflect truth, take care of it so it aligns. The more representative the readme is the more value you’ll get out of it. This benefit only surfaces by constant effort.
• Alignment: by aligning on the basis of written text it becomes easier to avoid misunderstanding. Everyone nodding over some text formulated together is the best indicator that everyone understands the same thing.
• Time saver for discussions: this effort is well offset over time by being a great reference for your discussions, as well: instead of opening up topics over and over, you can as well link to something that was agreed upon and written down in the readme already. Your memory might not be reliable enough, also your memory is not as convincing as something written down and on top of that, convincing is time-consuming in the first place. So save that time!
• Onboarding and research: Another time saver resides in the field of onboarding. Be deliberate about the readme and other documentation with your new team members. If they stumble over some problem that could have been solved by better documentation, let them put it there on their own. This creates a great feeling of responsibility that can carry on to daily work. And of course the next one to face this problem won’t have to do the nasty research anymore. Don’t forget to ask new team members what was hard during onboarding and draw your conclusions on how better documentation can help with those problems, in general. Everything else would be a missed chance in getting an outside perspective so you can document stuff that matters most! All that said, it’s not only relevant for onboarding, it’s even extending beyond that every time we research any information we need in order to complete the tasks at hand. So may it be for new hires or other daily research work, the return of investment is recurring!
• Stay flexible: having something written down is not an argument to beat down new discussions, of course. Discussion is vital and your team should stay approachable towards new ideas and changes. When talking about new ideas, sometimes it can even be helpful to have something written down to start from instead of something that only exists in the heads of the team members.
• Take deliberate action: When the readme doesn’t fulfil its purpose, be as deliberate with it as you would be with code. Too much complexity? Reduce it! Unnecessary or outdated? Consider removing it or keep it up-to-date. The option “don’t do anything” just spurs confusion.
• Think about the “where”: Code comments can be considered documentation too, but often they don’t give you a bigger picture, they aren’t really meant for that. So don’t be afraid to move content across comments, readme entries (or eventually company wiki pages) depending on what’s the best place. In general, code comments are most low-level, the readme can be higher level and everything above that usually resides in the company wiki (e.g. system architecture, design or business-related stuff).
• Single source of truth: The fewer places there are that need updating when something changes, the better. So better maintain a piece of information in only one place, e.g. the readme or the company wiki, but not both. Deep technical specifications—such as component models, logical database designs, or interaction diagrams (UML)—are often better suited for dedicated places. Don’t be afraid to link across comments, readme and wiki pages. Duplication is not a bad thing in code only, but also for documentation.
• Don’t overdo it: The aim should not be to avoid the need for thinking altogether (for that we have ChatGPT 😉). Documentation creates maintenance cost, so it’s key to strike a good balance.

I hope this article gave you some interesting food for thought, happy coding and (hopefully not too much) documenting!