Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Docs as-code-missing.-manual


Published on

Jennifer Rondeau and Margaret Eker presentation from Write The Docs Prague, 2016:

Treating docs as code, an approach that more and more teams and companies are moving toward, involves more than putting the two together in a source repository. We discuss some of the details that often get lost in as dev and docs learn to work together in new ways. Because if all we do is put doc files next to code files in source control, or use parts of the same workflow for code and docs, we're still isolating docs as a separate sort of responsibility, free from the obligations of systematic review and testing without which code would never be accepted into production.

Published in: Technology
  • Be the first to comment

Docs as-code-missing.-manual

  1. 1. Margaret Eker @meker meker12 Jennifer Rondeau @bradamante bradamant3 Docs as Code: The Missing Manual
  2. 2. Thanks to all
  3. 3. “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 (
  4. 4. “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)
  5. 5. –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.”
  6. 6. 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?
  7. 7. Release planning Doc Req Doc Design Plan Design Templates, stylesheets, info architecture, content strategy, doc project plan, and schedule Requirements analysis Use cases, scope of work, required deliverables User stories + Code + Tests + Docs + UI + UX
  8. 8. Scope of work Audience Updates (bug fixes) New features New product or service
  9. 9. Design Specify types of documentation required Specify the content model, content type templates Understand deployment models
  10. 10. Development Write Doc Review Develop Review Developmental 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
  11. 11. Assumptions Source formats Source storage Content models and templates Contributor collateral Training
  12. 12. Develop content Research Outline Write Submit (Commit, automated build deployed to staging)
  13. 13. Test Spell check Quality checklist User acceptance testing?
  14. 14. Review (pull request) Developmental edit Preliminary draft (self review) Technical review (user stories, product implementation) Editorial review (Style guide) Final review (Quality checklist)
  15. 15. DONE Doc Finalize Doc Publish Release Doc publish Integrate with product, push to production web site, package for distribution Final updates Apply final edits, sign off User stories + code + tests + docs + UI + UX
  16. 16. Code workflow Develop 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
  17. 17. 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
  18. 18. docs learn from code Write 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
  19. 19. Hard part #1
  20. 20. 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.
  21. 21. doc tests Linters = the unit tests of documentation Integration tests for docs? Regression tests for docs? Acceptance tests for everybody?
  22. 22. 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)
  23. 23. Resources
  24. 24. Hardest PART Establishing and maintaining open communication and collaboration across teams (Trust)
  25. 25. Write the Docs, together!
  26. 26. Margaret Eker @meker meker12 Jennifer Rondeau @bradamante bradamant3 thank you!!!