Docs for Developers

This is very concise book for learning how to write and structure effective documentation as a developer. The book uses a fictional company’s product as a way to put theory into practice, by providing implementation examples along the journey. I found the book highly enjoyable and easy to read, it completely fulfill it’s purpose of introducing the reader to the world of documentation and provides references to dig a bit deeper if you are interested.

I’ll definitely recommend this book to my developer friends. Still, there are two notes that I consider important to know before reading it. The first one is about the perspective when writing documentation, it is commonly assumed that documentation is targeted for customers or external users, I believe this case will continue to exist but it will be increasingly common to have a need for internal documentation as we become aware of its benefits. The book mentions once or twice that documentation can be internal as well, and all of the content will hold true for internal documentation, but it is clearly written with external users in mind. Probably it is this way because customers would be part of any business plan and their needs are a fundamental part of any business being profitable, so those are very visible for executives, I would say internal documentation can have an impact as big for a company if done right because it can greatly improve efficiency, significantly reduce the time to market for new features, and as an added bonus, increase developers happiness.

A document is good when it fulfills its purpose.

In my opinion the book should start with the quote and probably with chapter 9, the one including it. It is not a quote from the authors but a quote quoted from another publication, still I think it is of uttermost importance when writing documentation, to answer the question: what for? And that is what my second comment is about, I would structure the book in a little different way. I think it would be super nice to have a TLDR; convention for books, but until that happens, I think one of the hardest parts of writing an educational book is to know in which order present the topics because you never know what readers will read.

I don’t consider the actual ordering to be bad, since it is a very hands-on approach, but from experience I would say it is often a good idea to slow down a bit and consider costs, in terms of effort, time and money, beforehand. So I would move the last three chapters to the beginning of the book. The audience depends on the purpose and the purpose often become very clearly defined when you try to measure quality, because, as the quote express, those are intrinsically related. Once you have an idea of the purpose and therefore the audience and the metrics you can think about the structure of the documentation, not from the writer point of view but from the consumer, and get a roughly estimate of the cost it will take to produce it, including the cost and effort to maintain, which is medium and long term and as a consequence easy to miss in all the excitement of joining a new initiative.

I often hear people saying that if it is needed it must be done no matter the cost, or even better, disregarding the cost, which often means not being fully aware of it. I find that a naive affirmation, and as it is stated in the book and in many other places, poor documentation is worst than no documentation.