Margaret Eker @meker meker12

Jennifer Rondeau @bradamante bradamant3 yourmom.io

Docs as Code: The Missing Manual

Thanks to all

“Docs as code” ??Web delivery

Continuous integration for documentation

Collaboration for documentation using code systems

Content management using code systems

Definition of docs as code from Anne Gentle from her blog about modernizing technical documentation

(https://justwriteclick.com/2016/08/13/modernizing-technical-documentation/)

“Docs as code” ??

Docs in repository together with or close to code

Lightweight, plaintext markup language

Build to HTML using simple static site generators (Jekyll, Harp) or doc generators (Sphinx, Asciidoctor)

Multiple stakeholders

Iterative (assumes agile development model)

–Noirin Plunkett, Write the Docs NA 2013

“I imagine most of you are writers, work with writers, know writers. I've been a professional writer for almost a decade ... and my process when i write something basically goes, I research, I draft, I read my draft, I edit my draft, I read my second draft, I edit that, I ask somebody who isn't an expert to read it, I edit based on their comments, I ask someone who is an expert to read it, I edit based on their comments. Hopefully I then read it again, because all of those edits sometimes need a final edit to kind of connect the pieces that have gotten disconnected. And then eventually I publish it.

So what do all those edits give me, that I don't get when I just dash off an email? Some of them clarify content, some of them change the register ... some of them put in emotion ... we speak with our fingers.”

How do we reconcile?

The “missing manual” -- map this kind of doc workflow to emerging model of docs-as-code

Details missing from doc and code workflows

Map doc workflow

Map code workflow

What can we learn?

Release planning

DocReq

DocDesign

Plan

Design

Templates, stylesheets, info architecture, content strategy, doc project plan, and schedule

Requirements analysisUse cases, scope of

work, required deliverables

User stories + Code + Tests + Docs + UI + UX

Scope of workAudience

Updates (bug fixes)

New features

New product or service

DesignSpecify types of documentation required

Specify the content model, content type templates

Understand deployment models

Development

WriteDoc

Review

Develop

ReviewDevelopmental edit, technical review, design review, business review

Develop

Work with product and development team to

research, create content (words,

images, diagrams, and samples)

User stories + Code + Tests + Docs + UI + UX

AssumptionsSource formats

Source storage

Content models and templates

Contributor collateral

Training

Develop contentResearch

Outline

Write

Submit (Commit, automated build deployed to staging)

TestSpell check

Quality checklist

User acceptance testing?

Review(pull request)

Developmental edit

Preliminary draft (self review)

Technical review (user stories, product implementation)

Editorial review (Style guide)

Final review (Quality checklist)

DONE

Doc Finaliz

eDoc

Publish

Release

Doc publish

Integrate with product, push to production web site, package for distribution

Final updatesApply final

edits, sign off

User stories + code + tests + docs + UI + UX

Code workflowDevelop code architecture (design)

Build out framework (or work with existing)

Write tests

Write code against tests (ideal)

Build branch, run unit tests

Debug

Additional tests: integration, regression, acceptance

Debug

Merge to master

Documentation workflow

Develop information architecture (“developmental edit”)

Write first draft

Send for review

Revise/edit

Send for additional reviews as needed

Revise as needed

Publish

docs learn from codeWrite locally

Edit locally (?)

Build branch locally

Submit pull request

Participate in PR discussion; discuss as appropriate in issues

Revise

Resubmit PR / respond to additional forks, PRs

Repeat as needed

Branch builds until PR merged to master

Hard part #1

Hard part #2

OMG I have all this super cool stuff to tell you and I can’t wait to explain All The Things. Here they are in no particular order: 1. I LOVE THIS API. 2. What’s an API? 3. I cannot figure out what this API does. I wish I didn’t have to write this documentation. I can’t figure out what to write. I hate writing. I love writing, but not this stuff. I am terrified, I cannot possibly let anyone else see this terrible stuff I don’t really understand but someone told me to write documentation so here I am. I cannot possibly let anyone else see this imperfect piece of dreck because I am really meant to be a poet but I am sadly lacking in a room of my own and 500 euros a year or whatever the current equivalent of Virginia Woolf’s bourgeois fantasy might be. So I write beautifully perfect technical documentation but this is not it so I refuse to put it on GitHub or otherwise let anyone else see it until it is absolutely perfect and complete.

doc tests

Linters = the unit tests of documentation

Integration tests for docs?

Regression tests for docs?

Acceptance tests for everybody?

DoCS AS Code for You?

Docs as code development environment including CI/CD

Content models and templates

Shared project planning processes and systems

Contributor collateral (Readme, Contributing information, Contributor Guide, Style Guide)

Establish review guidelines and workflows (GitHub pull-request)

Cross-training for contributors (Git for Teams, documentoring, and so on)

Resources

Hardest PART

Establishing and maintaining open communication and collaboration across teams (Trust)

Write the Docs, together!

Margaret Eker @meker meker12

Jennifer Rondeau @bradamante bradamant3 yourmom.io

thank you!!!