Get Started with Docs as Code
We've transformed the way teams work together on docs, and we want to show you the best practices for writing docs using development tools and techniques. Now available in both print and ebook, check out Docs Like Code.
Why use GitHub for docs? If you're unsure of a good fit for your projects and teams, read about the potential wins with these techniques. Or, you may learn how to convince others who need to hear about the use cases.
Information architecture and workflows, how do you choose? Read these chapters to find out lessons learned when making sure the users are served first.
How can I improve upon my team's work? Author and build content like a pro, whether you're a writer or a developer. Build in quality assurance, automate builds, and review with your teammates to make great docs.
What are the best practices for REST API docs? While Swagger/OpenAPI, RAML, and other standards work well when considering the entire API lifecycle, you can also consider collaboration gains with simple markup and narrative documents beyond the REST API reference doc set.
Who's using these techniques?
“I met with one of the devs today to go over a Pull Request that I had submitted with editorial comments, and in the course of conversation, I mentioned that I had not been working directly with developers for very long.
He replied that he’d worked with technical editors in the past who were not very helpful, but that I was different. In fact, he assumed I was a developer at first because I was working in GitHub, effortlessly creating PRs!”
— Kelly Holcomb, Senior Technical Editor, Oracle
“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
If you haven’t read about it yet I’d recommend you to read - @annegentle #DocsLikeCode” #software #product #Documentation #SaaS #tech #techcomm #technology #technicalwriting #techwriter #knowledgebase https://t.co/ferLQvgRPQ— Sriram Hariharan (@Sri_AT72) February 14, 2018
#docsLikeCode refers to the use of repos like #git for source/version control and doc generation. It facilitates #agile docs, in the same sprints as agile dev. Ref https://t.co/JUp8fQoGRs, cc @annegentle— Mike Jang (@TheMikeJang) December 6, 2018
We do this for all documentation at @GDSTeam. The brilliant @annegentle has even written a book on 'docs as code' and has some ace case studies and guidance on her website https://t.co/AdPBAdRr7H. It works so well!— Jen Lambourne (@Jenny__Anne) February 26, 2019
"Docs as Code" is the search term you're looking for! #lca2019 #techcomm #docsascode— Lana (@Loquacities) January 21, 2019
Also, the wonderful @annegentle literally wrote the book on it :)— Lana (@Loquacities) January 22, 2019
Just finished @annegentle's new book, Docs Like Code, and it's outstanding for devs. If you value quality docs, see https://t.co/pVbhOcB3Bx— Carol Willing (@WillingCarol) March 1, 2017
@annegentle My trick? Treating docs like code! 😉https://t.co/NuuTgJcs3M— Carolyn Van Slyck (@carolynvs) March 12, 2017
Just finished "Docs Like Code" by @annegentle - Superb advice for modern technical writing. https://t.co/jI9jsA0OIy— Doug Hellmann (@doughellmann) March 7, 2017
This one just moved to the top of my reading list. A book on how to treat docs like code by @annegentle. Awesome! > https://t.co/nRkSZkhv5x— Patrick Andriessen (@napnamPat) March 6, 2017