Docs-as-code

tools and workflows

By Tom Johnson / @tomjohnson
Slides: http://idratherbewriting.com/docs-as-code-tools-and-workflows

Video recording

The following is a video recording of this presentation.

What I'll talk about

Why docs-as-code is trending
Scenarios where docs-as-code works well
Common tools and workflows
Challenges and pain points in this space
Experiences in implementing docs-as-code
Reflections on maturity and momentum

"Blogging like a hacker"

"On Sunday, October 19th, I sat down in my San Francisco apartment with a glass of apple cider and a clear mind. After a period of reflection, I had an idea. While I'm not specifically trained as an author of prose, I am trained as an author of code. What would happen if I approached blogging from a software development perspective?"— Blogging like a hacker, Tom Preston-Werner, co-founder of Github

What would happen if we approached software documentation from a software development perspective?

Getting rid of the database

What is docs as code

Plain text files (.md)
Static site generators
Text editors (Atom)

Git for file mgmt/collab.
Continuous publishing
Validation scripts

Why this started happening

Doc sites built using docs-as-code

More details »

Demo of how it works

< exit slides >

Top static site generators

Complaints from DITA people

No standards
No semantics
Not robust enough
No PDF
Poor localization workflow

Case study I: Implementing docs-as-code at Experian

Requirements

Modern-looking website	» Use Bootstrap
Re-use across outputs	» Separate config files
Version each release	» Copy file snaphots
Authenticate via Salesforce	» Upload into Salesforce
PDF for pre-sales distribution	» Use Prince XML + script

Jekyll doc theme I built

Regrets

Spent a lot of time developing tooling
No continuous delivery implementation
Salesforce authentication required tedious upload
File accumulation exponential with versioning
Created PDFs without ensuring actual need

Case study II: Implementing docs-as-code at Amazon

Requirements

Publish to old and new system	» 2 layouts; links == variables
Integrate design into website	» Namespace classes, body only
Publish through engineering	» Wait ... build pipeline from git
Authenticate some content	» Use custom A/B testing tool
Enable engineers as authors	» Branches, Markdown, Git
Support localization— 3 langs	» Containers referencing HTML

Jekyll theme I built

Solution for Appstore docs

Regrets

Spent a lot of time developing tooling
Didn't build-in support from business for doc tooling
Localization workflow cumbersome/klugey
Two-repo architecture requires manual copy/paste
Jekyll build-time slow; maybe use Hugo instead
Hard to prevent Git disasters in open system

Overall thoughts

Insist on 3rd-party tooling, hosting, deployment
"Build tools yourself on own time" == not good
Tools are incredible flexible if you have mad skillz
Freedom to code exact solution is unparalleled
Still very early in this space, so be patient

The first telephone ~ tin can

Bell and an early model of the telephone

More details »

Disruptive innovations

Social coding is empowering

429 forks of my doc theme

Discussion / questions?

Challenges & solutions

Designing the Site?

Solution: Bootstrap

Or have your UX team build it

Content re-use?

Solution: One project, with includes

Store content in _includes folder. Then insert like this:


{% include myfile.html %}

Or with parameters:


{% include myfile.html audience="java-developers" %}

Conditional filtering?

Solution: Liquid


{% if site.audience == "administrators" %}
show this to administrators
{% elsif site.audience == "analysts" %}
show this to analysts
{% endif %}

Multiple outputs?

Solution: Multiple config files

Sample build command:


//build administrators output
jekyll build --config config_administrators.yml --destination ../outputs/admins

//build analysts output
jekyll build --config config_analysts.yml --destination ../outputs/analysts

Multi-level nav menu?

Solution: YAML data file


- title: Overview
  output: web, pdf
  folderitems:

  - title: Get started
    url: /index.html
    output: web, pdf
    type: homepage

  - title: Introduction
    url: /mydoc_introduction.html
    output: web, pdf

  - title: Supported features
    url: /mydoc_supported_features.html
    output: web, pdf

And Navgoco jQuery component

Notes, tips, cautions?

Solution: Includes with Parameters

Create the note.html include:


Note: {{include.content}}

Use it like this:


{% include note.html content="Note content here ..." %}

Avoiding broken links?

Solution: Validate via scripts

PDF output?

Solution: Prince XML

Or live without it.

Git workflows?

Solution: Keep processes simple

Search?

Solution: 3rd-party service

Or have engineering custom-build it

Translation?

Containers for HTML

Output page body to HTML, reincorporate body. Maintain frontmatter.

Authentication?

Solution: 3rd-party service

Or have engineering custom-build it

Your docs-as-code journey?

The end

Tom Johnson
— idratherbewriting.com
— @tomjohnson
— [email protected]