Anne Gentle, Developer Experience Manager, Cisco DevNet

November 2019

DeveloperWeek Austin 2019

Docs Like Code: Strategies and Stories

Hi, I’m Anne Gentle

• I’m a Developer Experience Manager for Cisco DevNet.

• We treat docs like code for over 1000 code repositories for multiple developer products and platforms at Cisco.

• I’ve written a book and site, Docs Like Code, and docslikecode.com, to provide better onboarding for these techniques, with a few of my colleagues.

• Find the story about Cisco DevNet on justwriteclick.com.

Adventures in robot vacuuming

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

Why now?

Workplace evolution

Technology changes

Market and business needs

Flickr: candelabrumelabrumdanse

Goals for Docs Like Code

“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

• Scale

• Collaboration

• Ownership

• Value

Goals

Flickr: writethedocs

Plan Docs Like Code

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

Plan for deliverables Plan for business

• Sheer size

• Print or offline needs

• Integration

• Translations

• REST API standards

• Release timing

• Moving private APIs to public

• Licensing

• Limited access for contributors

• Globalization

“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

Automate Docs Like Code

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.

Build drafts with code builds to get more technical reviewers.

Scrape code comments to build docs.

Automate for efficiency and accuracy

Flickr: photohome_uk

Build drafts with code builds to get more technical reviewers.

Scrape code comments to build docs.

Automate for accuracy

Flickr: mortimer

Test Docs Like Code

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

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

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

Publish Docs Like Code

Static Site Generators: Jekyll, Sphinx, Hugo

Source Control: Bitbucket, GitHub, GitLab

Continuous Integration: Jenkins, Travis CI, Circle CI

Go-to tools at docslikecode.com/learn/

Decrease access, increase complexity

Open source + open output = simplest

Publishing workflows

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

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

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 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

Read more, ask questions

• codewriting.org

• docslikecode.com

• www.infoq.com/articles/ci-rest-docs

• Idratherbewriting.com/learnapidoc/

• writethedocs.org