When you treat docs like code, you multiply everyone’s efforts and streamline processes through collaboration, automation, and innovation. The benefits are real, but these efforts are complex. The ways you can leverage developer process and tools vary widely. Let’s unpack the absolute best situation for using a docs as code model. Then, we can walk through multiple considerations that may point you in one direction or another. We can talk about version control, publishing, REST API considerations, source formats, automation, quality controls and testing, and lessons learned. Let’s study best practices that are outcome-dependent and situational, creating strategic efforts.

1. Austin CIDM RIDE Conference
December 2017
Anne Gentle
Docs Like Code:
Strategies and Stories

2. Hi, I’m Anne Gentle
• I’m a Developer Experience Engineer
for Cisco DevNet. (Brand new!)
• Managed a team of writers for private
cloud product built on OpenStack.
• Lead community documentation
projects.
• Treat docs like code for over 300 code
repositories for 30 REST API services.
• Wrote a book and site, Docs Like
Code, to provide better onboarding for
this technique.

3. Adventures in robot vacuuming

5. Define docs like code
• Version control for source files
• Automatic builds
• Continuous integration
• Test
• Review and merge
• Publish automatically after
requirements are met
• Repeat
Flickr: stevensnodgrass

6. Why now?
Workplace evolution
Technology changes
Market and business needs
Flickr: candelabrumelabrumdanse

7. Goals for Docs Like Code

8. “The transformation has been a
measurable success. The number of
contributors has skyrocketed, from 6 to
175, we’ve reduced content build and
deployment time from minutes to
seconds…”
Margaret Eker, Rackspace
docslikecode.com/articles/rackspace-case-study/
• Collaboration
• Ownership
• Service
Goals
Flickr: writethedocs

9. “We chose to host our documentation
repository on GitHub to align ourselves
with tools and workflows adopted by
other teams across our organization for
better collaboration. Our secondary goal
was to tap into the collective intellect of
our developer community by allowing
public contributions.”
Rachel Whitton, Pantheon
docslikecode.com/articles/pantheon-case-study/
• Quality
• Trust
• Workflows
Goals
Flickr: stevensnodgrass

10. “I mentioned that I had not been
working directly with developers for
long. He said 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, Rackspace
• Web and mobile
• Content focus
• Value
Goals
Flickr: edwardconde

11. Plan Docs Like Code

12. Plan for users Plan for contributors
• Web or mobile experience
• Tight integration with as-a-
service releases
• Review with you
• Licensing and access to
source
• Complexity of authoring and
reviewing and building
• Speed of reviews and builds
• Accuracy for content
• Trusted set of reviewers who
can approve publishing

13. Plan for deliverables Plan for business
• Sheer size
• Print or offline needs
• Integration
• Translations
• REST API standards
• Release timing
• Licensing
• Limited access for
contributors
• Globalization

14. “Essentially, this means you’re laying
down a new highway while
simultaneously you’re driving down
it.”
Tom Johnson, Amazon Lab126
idratherbewriting.com/learnapidoc/
pubapis_switching_to_docs_as_code.html
• Standalone repository or
docs within code source
• Inclusion mechanisms
• Not final: move over time,
carefully
Source file
optimizations
Flickr: tabor-roeder

15. Automate Docs Like Code

16. Continuous
Integration/
Continuous
Delivery
for docs
By having a built draft ready for review,
casual contributors and reviewers avoid
the overhead of downloading the patch,
replicating the build environment, and
then building the docs. We can review
both the source and output thanks to the
automation in the system.
Andreas Jaeger and Anne Gentle,
Continuous integration and delivery
for documentation

17. Build releases with code
parameters to save time.
Build a site to a draft or
staging area for reviews.
Build a new deliverable in a
pipeline.
Automate
for efficiency
Flickr: photohome_uk

18. Build drafts with code builds
to get more technical
reviewers.
Scrape code comments to
build docs.
Automate
for accuracy
Flickr: mortimer

19. Test Docs Like Code

20. Make sure it builds.
Check links, internal and
external.
Test trademarked or product
name compliance.
Test REST API requests and
responses.
Quality tests
Flickr: turbojoe

21. Track doc bugs and
measure improvement.
Link to bug descriptions in
patches that fix the doc bug.
Write down review
expectations and train
reviewers.
Use a checklist, style guide,
reviewer guide.
Review strategies

22. Editing
Prioritize technical reviews
Provide pro-level editing overall
“For example, when working with
the production team at O'Reilly on a
line-by-line copy-edit of the entire
OpenStack Operations Guide, the
team had multiple writers at the
ready, able to enter their edits. The
O’Reilly production team uses a
quality control process: both a
copy-edit stage and copy-edit
review stage, where someone
verified that all suggested edits
were made.”
Docs Like Code, Professional
technical publishing of books on
GitHub

23. Publish Docs Like Code

24. Decrease access,
increase complexity
Open source + open
output = simplest
Publishing workflows

25. Straightforward
• Open source
• Web output only
• Standalone web site
• Mac and Linux only
• Employees only
• Small teams
• Reviews by core team
• Publish rights for a few
• No logins required in output
• Single repository

26. Complex
• Closed source
• Print and web
• Integration with application
or larger site
• Cross platform, with
Windows
• Non-employees
• Large teams
• Multiple source repositories
• Reviews by all
• Publish rights for many
• Logins to access output

28. Natural tension areas
• Tech writers who used to be
responsible for all deliverables now
have to rely on other teams for
integration work.
• Managers of higher-paid
developers want to make docs the
problem of lower-paid writers.
• Contributors with Windows
machines can’t easily build with
with dev tools used for static site
generators and modern web
development like Jekyll.
• Privacy and access control for
docs source means docs teams
have more difficulty collaborating
outside of their immediate team.
• Getting resources for web
development that’s unrelated to
product development.
• Who gets to control what gets
done when? Dev or Doc? Product
or Support? Content strategy
overall across disparate source.
• Style guides, image standards, tool
standards, basically, agreement.
Eddie Kopp

29. Data-Driven Docs and Code

30. - Ed Catmull, Creativity, Inc.
“Measure what you can,
evaluate what you
measure, and
appreciate that you
cannot measure the
vast majority of what
you do.”

31. Project started by Troy Howard, dev
docs writer at Twitter.
The idea is to build tools that analyze
the large communities for more than
anecdotal evidence.
codewerdz.org
• What is the ratio of code to
docs, in terms of overall
character volume?
• For commits that are a mix of
code and docs, what is a
typical ratio?
• Does the overall size of the
team affect this ratio?
• What is the code-to-docs ratio
for each contributor?
Codewerdz – analytics for code and docs

32. Learning together

33. Read more
• codewriting.org
• docslikecode.com
• Idratherbewriting.com/learnapidoc/
• writethedocs.org
• codewerdz.org