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

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]