This book is meant as a resource for technical writing teams who are using, or are moving toward, a docs-as-code approach. The first edition was published in 2017, and I read the third edition, published in 2022. Anne Gentle (Cisco) and Diane Skwish are co-authors, and Kelly Holcomb (Oracle) is listed as a contributor. Eric Holscher (founder of the ReadTheDocs platform and the WriteTheDocs community & conference) wrote the foreword for this edition.
At only 127 numbered pages, this book is slim but densely packed with useful information. There is a lot of technical detail, so I don't consider it suitable for anyone brand new to software documentation. Mainly, if you have never used git (a software version control and collaboration system), the many discussions on git pull requests and git branches and such won't make much sense to you. This book is not intended to teach you these concepts. It does, however, provide a list of resources for learning git, and a glossary of git-related terms and definitions.
Docs Like Code contains four chapters:
The first chapter defines a docs-as-code framework as one where you:
The second chapter (Plan for docs as code) includes sections on:
Many topics are covered in these sections, from choosing a markup language (Markdown, AsciiDoc, RST, etc...), to using mermaid diagrams, to determining API complexity, to choosing a static site generator. This book doesn't provide a deep dive into single topic; it provides seasoned advice and enough to get you started.
The requirements gathering section presents a wide variety of useful questions, such as:
The third chapter (Optimize workflows with docs as code systems) is the thickest of the four. It's also where prior knowledge of how to use git is most necessary, as much of it is concerned with git-based workflows.
Questions considered in this chapter include:
This chapter also includes advice on using a CODEOWNERS file, creating a docs contributors guide, writing a style guide, building locally, automation, review processes, versioning, and more. Many useful docs-as-code tools are recommended, such as the prose linter Vale, broken link checkers, Docker, GitHub Actions, Jekyll, and others.
The final chapter (Lessons learned with docs as code) is the thinnest - only 9 pages, with a few paragraphs devoted to each of these lessons:
This book does not contain any information about the use of AI in docs-as-code, aside from mentioning the rise of AI/ML in documentation.
There is no index, which I found disappointing. Considering the breadth of topics covered, an index would be quite useful.
This book is not a tutorial. It will not teach you how to use docs-as-code. However, it's an extremely useful book that covers countless facets of docs-as-code. Pick it up if you're thinking about switching to docs-as-code or if you want to figure out holes in your existing approach that need to be considered.
Review coming soon!
Review coming soon!