At one point or another during a project, we need to document the work we do. The more software we create, the more documentation we ought to write. I have rarely seen a project free of documentation that was straightforward to jump into, one of two things would explain it. The first option is an empty project, not all that interesting. The other is a wrapper project that merely wraps on top or blends within an already well-documented project or tool. An example of the latter would be a configuration repository full of Kubernetes definitions relying on images of well-documented applications, internal or external.
Anything else needs enough documentation for a developer to clone the repository and run something in a reasonable time. As you know from a previous post, documenting enough for a peer to get started within ten minutes is my personal target.
Now the question is, where should that documentation be? I met people that would argue for a Word document and even some psychopaths that would deliver paper documentation. As in hundreds of pages documenting a system. You know, that thing that if you release software every few weeks has the potential to make you the Amazon forest worst enemy. Bin all that crazy talk. What about tools like Confluence? It’s eco-friendly, no paper to burn nor Word documents to continuously maintain. It works right? Well, yes and no. Confluence is great. The end.
But wait, there’s better. At least in my book. Even tough Confluence is great to socialise a project its stakeholders, I don’t believe it helps developers all that much. Just imagine, you go consult on a project and get given a bunch of repositories to magic through but have no idea to get started. The guys that worked on these repos are either gone or too busy to give you any information. You will search through the Confluence variable and filenames you can’t make sense of hoping there is some documentation. An hour may pass before you get anything remotely close to what you can do within that repository.
I found myself a few times in situations where I had to go through several repositories examining every piece of code and comment available in there to get a glimpse of what was going on. In worst cases no documentation was available, others had bits in Confluence and yet all these times felt equally horrible.
Do you want to know in which context I have a great time discovering a codebase? README.md. All the open-source projects to which people use and contribute to massively like during Hacktoberfest, all have that file in common. I believe this is the perfect place to write useful information to help developers help you. Ideally, the README would contain an example to run the software from the repository and good ones a way to run tests even if it seems obvious to do. Be good people and write README files. And please when you write them, focus not about what the software does but how it can be used will help you create a better experience for fellow devs.
If not by kindness, think about self-preservation. Back when I studied at ESGI, one of the teachers shared that quote with us about maintaining software. Write code as if the next person that will work on it is a psychopath that knows where you live. Back then it was a quote to be in a mindset but with social media nowadays who knows. You sign code with your name, people are a google search and a few clicks away from finding out where you hang out. Just document how to use your code in a README and nobody will cancel Christmas.
