Docs Like Code by Anne Gentle

Many people do not like to write documentation, or if they do, it’s often detached from the source code, leading to it quickly becoming outdated.

This is a common problem I’ve noticed in the majority of closed-source codebases I’ve had the chance to work with. I can only hope that I was the unlucky one, and your case is different :)

There are multiple strategies and tools you can use to improve the documentation coverage of your repositories.

This never-ending journey of improving the way code is documented led me to “Docs Like Code” by Anne Gentle.

I won’t get into what I was expecting from this book; I’ll just focus on what I really got.

First, I was lost on what the target audience of this book is. Is it for developers, managers, or dedicated documentation teams?

Which then leads me to the second point. If the book does not have a clear audience it’s directed to, it tries to touch on everything and nothing.

That’s what I feel was done here, with a definitely bigger shift towards non-technical people, mainly those who have never used GitHub before or had a chance to work with any of the static page generators.

The book focuses a lot on GitHub and Git, to the point where it explains basic GitHub features (protected branches, pull requests) and Git features (git flow, basic commands).

If you have even a small amount of experience with GitHub, Git, and static page generators, I don’t think you will find anything new here. If you don’t have experience with those tools, then I believe you will find better tutorials on the web that explain those.

For anyone who wants to increase their knowledge of building documentation close to source code, this book may be rather disappointing.