Write Drunk - Test Automated

4299314d91e1a92c72cfe9f7f4116ec5?s=47 sven
February 02, 2019

Write Drunk - Test Automated

Documentation Quality Assurance

- Tips and Tricks
- Start small, extend to CI



February 02, 2019


  1. 1 Write Drunk-Test Automated Documentation Quality Assurance Sven Strack -

    @der_sven_ - DocOps Engineer @ PRONOVIX
  2. 2 Hello! Nice to meet you • DocsOps Engineer •

    DevOps and SRE background • Plone • TestTheDocs • Write the Docs About Me - The least interesting part of this talk This talk is opinionated and I like to complain!
  3. Reality Check Facts ▪ Writing is hard ▪ Continuous Integration

    is not always easy ▪ There is no golden or perfect solution ▪ (Automated) checks can only help you till a certain level ▪ QA starts locally in your editor 3 Disclaimer ▪ Based on OSS Communities ▪ You may recognize your own commits
  4. The Golden Circle Well written and maintained documentation should be

    part of your internal and public company culture. 4 Takeaways Good documentation gets people to jump into your project quicker Good documentation will save an organization’s time,money and effort Lack of good documentation is a problem for acceptance
  5. It is not only about the front-end ! Care about

    your editors 5 Readable source is as important as the rendered HTML • Less frustrating • Easier to read and understand • Quicker edits = faster deploys
  6. 6

  7. 7

  8. Knowledge is beautiful “I love it when a plan comes

    together” 8 Planning • Define style guides • Define standards and values for checks Considerations • Start small, extend step by step • Start from the beginning • Know your audience • Know your contributors • Be strict and be friendly • Useful error messages
  9. Getting to know each other 9

  10. Getting to know the audience 10

  11. Developers are your friends ▪ Adjust to their workflow as

    much as possible ▪ Help them by using templates ▪ Add links to documentation in PR templates and error messages ▪ Only run checks on changed files 11
  12. Do not forget Friendly reminder 12 • Protect your branches

    • Validate all your checks according to best practices • Keep checks “simple” and “easy” to adjust • Start small • Make your checks depending on each other
  13. Continuous Integration “Docs as Code” 13 • Do not break

    the build • If you broke the build, FIX it • Do not merge a broken build
  14. Demo 14 Source: https://www.integraserviceconnect.com/wp-content/uploads/2017/11/FArtboard-1.png

  15. Here be dragons 15 Disclaimer This is only a demo

    setup for local usage Overview • Basic example with travis • Basic example running CI locally
  16. 16 THANK YOU !

  17. 17 THANK YOU Sven Strack - @der_sven_ - https://www.pronovix.com