Docs Like Code
Now in its third edition, Docs Like Code: Collaborate and Automate to Improve Technical Documentation has been a helpful book to many. What happens when you integrate documentation tightly with software code for products and services? You treat docs as code. Let’s find out the best practices and create a balance point between artisanal craft and automation efficiency.
We’ve transformed how teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. You can buy a printed book from Lulu or buy a paperback from Amazon now. The updated 3rd edition ebook is available now on Lulu and coming soon on Amazon or iBooks.
For the third edition, co-founder of DataCrunch Lab Rob Montalvo recently read a preview and said, “I found it very insightful, and (as a “former” developer) relatable. I think there is a lot of value to many organizations, particularly large/enterprise settings.”
If you’re simply curious about what docs as code is all about and want to learn more, you can sign up for three emailed lessons plus a free review checklist in a neat PDF file by joining the mailing list.
Here are a few reviews to pique your interest:
Anyone who wants to write excellent documentation should find value in this book. Whether you are an experienced writer or a developer who wants user focused documentation, this book provides the what, how, and why of modern technical documentation. As a developer who has also written documentation for several years, this book highlighted best practices for documentation success within a development team. From setting guidelines for developers and contributors to automating documentation testing, you will be guided step by step through proven, sustainable development/docs processes. Overall, I highly recommend to all who appreciate excellent documentation.
– Carol Willing, Director, Python Software Foundation
This book will be the go-to guide for people looking to get into the Docs like Code world. It has been on my list to write for a while, and I’m glad someone did for me. 🙂
– Eric Holscher, Cofounder of Read the Docs and Write the Docs
Conversation and Community: The Social Web for Documentation
I’d love to have you take a look at Conversation and Community: The Social Web for Documentation, available as a free ebook bundle.
Published by XML Press, this book offers you hard-earned lessons learned from practicing documentation with wikis, blogs, forums, and other social media methods.
You can read the table of contents to get a sense of what you can learn from this book. Here’s the text from the back cover:
Listen, then execute a successful social documentation strategy.
The technical communication world is on the brink of a major cultural shift from one-sided “documentation” towards user-generated content, collaborative communication, and the power of communities. This shift will change the way technical communicators work and will offer new opportunities to those who can seize them. If you are wondering where to start or what your future role may be, this book is for you.
Anne Gentle’s Conversation and Community brings social media alive through real examples and stories that will help you be a more successful technical communicator. It offers practical guidance and lessons learned from the author’s experience and that of other leaders in the field. It outlines the social techniques that have the greatest leverage and explains how they can help you start a conversation and build a community with your customers.
Here are a few quotes from reviewers. Links to the full reviews are available below.
“…the book has value to web workers of all stripes. The book is practical, up to date and isn’t just a “me too” social media tome.”
— Will Kelly, technical writer and contributor at WebWorkerDaily.com
“The consistent, confident, professional tone kept me riveted…”
“I highly recommend this book to both technical communicators and those involved in social media and community. My copy is going straight to my boss’ desk.”
— Jeff Osier-Mixon, Community Admin, Developer Advocate, and Senior Technical Writer
“Could be best TC read of the decade”
— Michael Hughes, user experience architect at IBM
“If you think community participation in your documentation is coming soon, read this book immediately. If you think that it’s not coming, you’re wrong, and you especially need to read this book.”
— Sarah O’Keefe, President of Scriptorium
“The book is brim full of useful information and, even better, great ideas”
— Sarah Maddox, technical writer for the Confluence documentation at Atlassian
This sample chapter is available to start the conversation. I invite you to comment on this post, or on Scribd.
Free Chapter Conversation and Community
Documentation as Conversation
One draft title for my book was “Documentation as Conversation.” It seemed fitting when staring at the sharp turn toward a new way of looking at tech documentation. But what I found as I kept working in the wiki world and facing the struggles that accompany collaborative authoring is this truth: that community support and management was as much a part of the brave new world as having individual back-and-forth comments on blog posts or discussions in forums. To get the keys to your conversation, pick up a copy of the book at Amazon.com and start the conversation your audience has been waiting for.
Reviews
Jeff’s Open Source Resource: Book Review: Conversation and Community, by Anne Gentle from Jeff “Jefro” Osier-Mixon in his Open Source Resource blog
Palimpsest: Let the conversation begin with Sarah O’Keefe on the Palimpsest blog
Future Changes: Book Review: Conversation and Community by Anne Gentle from Stewart Mader on Future Changes
Review of Conversation and Community: The Social Web for Documentation from Ellis Pratt on the Cherryleaf blog
Book review – Conversation and Community by Anne Gentle from Sarah Maddox on her “ffeathers – a technical writer’s blog”
Review of Conversation and Community: The Social Web for Documentation from Tom Johnson on I’d Rather Be Writing
Book review: Conversation and Community from Rhonda Bracey in her CyberText newsletter
Conversation and Community: a review (of sorts) in about 1,700 words from Scott Nesbitt on the Communications from DMN blog
Review of Conversation and Community – The Social Web for Documentation by Anne Gentle by Craig Haiss on HelpScribe
Reading:: Conversation and Community by Clay Spinuzzi on his blog, Spinuzzi.
Conversation and Community: The Social Web for Documentation by Will Kelly on Web Worker Daily
Conversation and Community in One Laptop per Child by Wayan Vota on OLPC News
Book Review: Conversation and Community by Anne Gentle by Peg Mulligan on her blog, Technical and Marketing Communication: Content for a Convergent World
A little something extra… by Red Monk analyst Michael Cote on his blog, People Over Process
OpenStack Books
I’ve had the privilege of working on a few published books in my career as an OpenStack documentation contributor. The OpenStack Operations Guide was the result of a five-day book sprint and I served as a coordinator and author. Here’s a video about our collaborative authoring experience. For the OpenStack Security Guide and OpenStack Architecture and Design Guide, I served as a connector and funding seeker for the authoring team. All three guides are still being worked on in the OpenStack community.
