[[Advent Dev Stories 20’]]'s [[Insta story]] on [[mjkonieczny's Instagram]] > 8. How to maintain useful [[Documentation|documentation]]? ![[ADS20-08 - Useful documentation.mp4]] Hey, today is the eighth day of [[Advent Dev Stories 20’|Advent Dev Stories]]. Today's [[Topic|topic]] is how I take care of useful [[Documentation|documentation]]. There are many kinds of [[Documentation|documentation]] - we have already mentioned [[API]] [[Documentation|documentation]] at some point. In today's [[Episode|episode]] I will focus on [[Project|project]] [[Documentation|documentation]], so in short - the README. I was wondering what to talk about - all sorts of practices, how to write such [[Documentation|documentation]] and so on - but in the end it came out that I would talk for 5 minutes and not reach any sensible consensus. So I changed my approach to this [[Episode|episode]] a bit and I will tell you about a [[Definition|definition]] I came up with on the spot, which I think covers the vast majority of cases. A good README is nothing other than the non-automatable minimum of [[Knowledge|knowledge]] that maximally lowers the barrier to entering the [[Project|project]]. It sounds a bit hardcore at first, but in reality it is not. So let me explain it piece by piece. Let's start from the very end - maximally lowering the barrier to entering the [[Project|project]]. That is fairly obvious. A good README is one where, if a new team member joins, they basically do not have to ask anyone about anything - everything follows from the README, they can just read it and get going. The same goes for us: if we had a longer break from the [[Project|project]], reading the README still lets us jump right back in. That is fairly obvious. The second part - the minimum of [[Knowledge|knowledge]]. That is not entirely obvious, because many people think the more they write in the README, the better. Honestly, it is definitely worse, for two reasons. First, it introduces unnecessary [[Communication|communication]] noise - it is hard to find your way around such a README. And second, it is a kind of debt - let's call it [[Documentation|documentation]] debt - that has to be maintained. Sooner or later we will not feel like doing it, and such a README will simply start to rot. And the last piece of the puzzle - actually the first - non-automatable. I think it is the most important one, because for anything that can be automated, the question is why it should be in the README at all, especially since we would then have to maintain it manually. And there are quite a few examples. Let's start with what the application does business-wise and how we know it actually works - [[Testing|tests]]. Good practices in code, how we write code - [[Linter|linters]], which can also be automated. Diagrams, schemas - another thing that can be generated, auto-generated from the code. So all those things automatically drop out of the README for me, because why put them there if they can all be generated? It would follow that I actually throw more things out of the README than I put in - and in practice that is true. Because if I can automate a lot, then why bother. The last things that, in practice, I keep in the README at all are only how to run the application and how to set up the whole [[Software development|development]] environment and so on - although lately even that is needed less and less, because in the era of dockerisation it is sometimes enough to run [[Docker Compose|docker compose]] and everything comes up. So, summing up: what I keep in the README is everything I cannot handle with some tools, everything I cannot automate. Those are the things worth putting in the README. It is also worth putting there any summaries of [[Problem|problems]] I ran into while getting the application running - for example links to Stack Overflow. That is definitely something that should be in the README, because someone else may run into the same [[Problem|problems]]. ## Other stories ![[ADS20-08 - Useful documentation 1.jpg|300]] ![[ADS20-08 - Useful documentation 2.jpg|300]] ![[ADS20-08 - Useful documentation 3.jpg|300]]