Docs Like Code

by Anne Gentle

Looking for a way to invigorate your technical writing team and grow that expertise to include developers, designers, and writers of all backgrounds? When you treat docs like code, you multiply everyone’s efforts and streamline processes through collaboration, automation, and innovation. Second edition now available with updates and more information about version control for documents and continuous publishing.

Genres: Nonfiction, Writing, Technology

185 pages, Kindle Edition

First published November 10, 2017

Reviews

[Robin · Rating 3 out of 5]

This book was targeted quite narrowly without explicitly acknowledging that fact. I found it very convincing for API and other similar reference documentation, especially if the primary audience of your doc set is developers or sys admins. The discussion goes deep but lingers overmuch in tooling, veering away from some of the ideas I most would like to grapple with: What about scenario-based documentation, where the relationship between individual items in the doc and discrete pieces of code is complex? What about mitigating transition costs if your docs have evolved elsewhere for years? What are some other examples of writing teams that have tried to treat docs like code, and what have been their experiences? This book starts the conversation about treating docs like code, but what it doesn't say could fill four times as many pages.

[Christina · Rating 2 out of 5]

This book is very...self-congratulatory. It should be retitled Docs the OpenStack Way or maybe even more specifically API Docs the OpenStack Way. I'm not saying there isn't good information here, it's just that every single point of reference, every example, every "learning" comes from OpenStack docs. If someone told me they found the cure for cancer but they could only quote their own work, I'd be very skeptical. While Gentle prefaces this as something that should be tool agnostic, every OpenStack description relies on GitHub, making the whole book very tool specific.

Another problem I had was the formatting and printing of this book. Why are the margins so wide and the shape so unwieldy? Shouldn't a tech writer know how online tech docs differ from a book? I don't want footnotes with links as if this was an online doc where I could click to learn more! A book should be largely whole and self-explanatory. And also related, why is the content format sometimes so...wrong? Like call outs where there should be a list, or tables that have their axes flipped...

There are parts I agreed with, but unfortunately the formatting and lack of breadth really overshadowed the good parts of this book for me. I can't really give a balanced, unbiased review. But when have my reviews ever been unbiased?

[Karen Cavalli · Rating 5 out of 5]

Makes transformation doable

Gentle’s book is a great companion to Tom Johnson’s API Documentation course on idratherbewriting.com. Gentle’s book provides talking points you can use to get leadership excited about and gain their approval for transforming the traditional documentation approach to docs-like-code. Then she digs into the detail a technical writer needs to understand how this whole docs-like-code thing works. She uses the book itself to exemplify this, since this was the approach she took to create and publish it. At the end she offers a tutorial to see for yourself how quickly this can be implemented. I’m in the midst of the tutorial so we’ll see!

[Scot · Rating 5 out of 5]

I thought this was a terrific introduction for technical communicators interested in migrating both their content source and philosophic paradigms to a code-based model. I think the book was broad enough to allow for multiple use cases and also specific enough for actual, pragmatic help in the here and now.

Even though I've used this model for years, I learned a few things in Docs Like Code that I'm going to take to my team and propose that put in practice. It's an awesome resource for any writer interested in honing their craft.

[Yuvi Panda · Rating 5 out of 5]

Written for ol' school technical writers

This book was useful in figuring out what kind of starting point someone who has been writing technical docs in the pre-github era comes from. I didn't learn much new. Is well written though!

[Nathan D. Riggs · Rating 3 out of 5]

/Docs Like Code/ reads more like a reference than a cohesive introduction to using asynchronous methods of producing technical documentation. The focus is also a bit more on the "process" side, which is currently contentious in the tech writing world (versus focus on content), but there's room for both. Honestly, I think this book is probably worth a read--it's extremely short--but you're going to need a lot more than this book to even begin to understand the process as it is applied online. Really, though, it's not too far off from the writing process we've identified for centuries: Write, Review (revise), Test (peer review), Merge (add to existing work from others), Build and Deploy (Publish), repeat the results. The biggest difference is in the speed at which this all happens now.

Again, worth a read for technical writing folk, but needs a lot more to make a rel impact.

[Lydia · Rating 3 out of 5]

I'm at the "getting my feet wet" stage of API writing, and I found this book useful, but also a bit like being tossed in the ocean. The case studies assume you are very familiar with specific tools, many of which I have never used. I was hoping for high-level context, buuut something that's true of tech writing in general is that context comes with experience.

The authors did bring up some important considerations that I might have overlooked on my own. I gained the most from the helpful process tables.

If nothing else, it's pleasant to read books written by tech writers who share my enthusiasm for the field.

[Cory · Rating 4 out of 5]

I wish there was a little more on end user/UI documentation. It's very focused on developer/API documentation, which is great for teams who only need to deal with that, but not for those of us who need to work on both.

On the positive side, this book was extremely thorough and clearly written by people with technical writing expertise. The length was perfect. The steps were at the right level of detail. The external links were helpful.

[Travis · Rating 5 out of 5]

An excellent primer with best-practices for anyone interested in treating docs as code. If you’re a writer and you need to co-author and collaborate with developers and you’re looking for mutual tools and scalable processes, or maybe you’re part of a DevOps team and you need to continuously publish updated docs with updated code, or you’re just interested in a modern technical writing approach—this book is a good place to start.

[Carlos Ramos · Rating 3 out of 5]

It has some good concepts, and I liked it more than "The Product Is Docs", but I would still say that the best and all you need about technical writing is "Modern Technical Writing".

This book has too much fluff and theory, repeating itself a lot, while giving some general advice that can be said is way less pages.

If you have it in your hands, read it, by all means. But if you are still deciding on a book about technical writing, "Modern Technical Writing" is the book I recommend.

[Bryan Jenks · Rating 2 out of 5]

Short, useful, but it just didnt really feel "meaty" to me.

[Valeria Hernandez Luzardo · Rating 4 out of 5]

This is a concise introduction to the docs-as-code approach to technical documentation and provides advice on how to start using it.