Write Drunk - Test Automated

Documentation Quality Assurance

- Tips and Tricks
- Start small, extend to CI

Transcript

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
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