ABOUT THIS BOOK
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.
BOOK CONTENTS
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:
- Introducing docs as code
- Plan for docs as code
- Optimize workflows with docs as code systems
- Lessons learned with docs as code
The first chapter defines a docs-as-code framework as one where you:
- Store the doc source files in a version control system
- Build the doc artifacts automatically
- Ideally, run automated tests on the docs
- Ensure that a trusted set of reviewers meticulously review the docs
- Publish the artifacts without much human intervention
The second chapter (Plan for docs as code) includes sections on:
- Requirements gathering
- Planning for automating, testing, and site hosting
- Organizing source files and repositories
- API reference documentation
- and more
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:
- Does the source repository need to be private or can it be publicly available?
- How do users access the docs, and how often from each platform?
- How much [of the budget] should you allocate per author, per deliverable, and for hosting?
- Are you relying on an internal team or a third party to have "pager duty" if the docs site goes down?
If you are a team planning to adopt docs-as-code, this section alone is worth the book as a useful checklist for everything you need to consider.
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:
- Are the docs in their own repo?
- How will you publish?
- Will contributors preview docs locally or on a server?
- How will you collaborate with others?
- How many pull requests and reviews do you expect?
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:
- Find your community and learn from others
- Create a great web experience
- Equip your contributors with a style guide
- How will you collaborate with others?
- Empower your contributors
- Write a contributor's guide
- Write a reviewer's guide
- Build in continuous integration for docs
- Teach everyone to respect the docs
- Test and measure outcomes
- Set up a Git support chat room
What's not in this book
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.
Overall
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 about 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.
Learn more about docs-as-code
- Docs Like Code (a companion website to the book, with supplementary articles and tutorials)
- Write The Docs - Docs As Code
- I'd Rather Be Writing - Docs as code
- I'd Rather Be Writing - Docs-as-code tools
Top comments (0)