Date post: | 16-Apr-2017 |
Category: |
Technology |
Upload: | margaret-eker |
View: | 413 times |
Download: | 0 times |
Margaret Eker @meker meker12
Jennifer Rondeau @bradamante bradamant3 yourmom.io
Docs as Code: The Missing Manual
“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
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
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 #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)