How to Write Better Documentation and Bring Balance to the Force

Good documentation is often the best marketing for technologies, frameworks and products: It makes complex systems more accessible, increases developer efficiency and reduces errors. However, writing documentation is often perceived as a chore, which leads to poor quality.

In this talk, I will show you how to document with structure and clear frameworks. Firstly, we will look at types of documentation, structural standards and suitable styles. In the technical part, we'll look at how to manage extensive documentation from multiple repositories, create easily searchable pages and use linters for consistent style.

Transcript

1. qaware.de How to write Better Documentation and bring balance to the Force Alex Krause alex.krause@qaware.de @alex0ptr Klassifizierung: Öffentlich
2. What is the original Star Wars about? (spoilers) 2 QAware Episode II: Count Dooku (yes, this is his name) brought the Death Star plans from Geonesis to Darth Sidious. Rogue One: Galen Erso, laser gun architect, made modifications to the plans to intentionally introduce a flaw: an unlucky positioning of an exhaust that leads to the superlaser reactor. These plans are later stolen and transmitted to Alderaan. The original Star Wars opens with princess Leia hiding the Death Star plans in R2D2 which is tasked to bring these to a Jedi. This ultimately leads to Luke Skywalker using the flaw and destroying the Death Star.
3. 3 QAware Star Wars is a Saga about how good documentation is worth risking your life for and why documenting technical debt is essential to bringing peace to the galaxy.
4. 1. Why? 2. How? 3. Tooling
5. Why we need great documentation … or what is disturbing the peace?
6. Problem: StackOverflow driven development 6 QAware “[...] developers use Stack Overflow as a major resource for solving programming problems [...] Other resources, such as official Android API documentation, do not provide the same degree of quickly understandable, directly applicable assistance. Our results suggest that using Stack Overflow helps Android developers to arrive at functional solutions more quickly than with other resources. [...] Because Stack Overflow contains many insecure answers, Android developers who rely on this resource are likely to create less secure code.” - You Get Where You're Looking for: The Impact of Information Sources on Code Security 2016 (10.1109/SP.2016.25)
7. Security and Compliance for the Galaxy 7 QAware “Documentation is also critical. [...] this suggests the importance of creating official documentation that is useful enough to keep developers from searching out unvetted, potentially insecure alternatives. [...] the excellent code examples for PyNaCl and in the cryptography.io “recipes” layer appear to have contributed to high rates of security success.” - Comparing the Usability of Cryptographic APIs 2017 (10.1109/SP.2017.52)
8. PRODUCTIVITY “Documentation predicts productive and happy individuals and organizations” 8 QAware “Sharing and sourcing knowledge through different forms of documentation improves productivity both in open source projects and at work.” - GitHub Octoverse 2021 - State of DevOps Report 2023 for the galaxy
9. 9 QAware Good documentation is an enabler for successful products
10. Every Product needs Documentation Imagine assembling furniture without a manual. 10 QAware
11. How do we write good Documentation?
12. Example 12 QAware K8s Platform Guide 1.Getting Started 2.Security 3.Continuous Delivery 4.CI/CD Includes 5.CLI 6.ArgoCD 7.Prometheus 8.Traefik 9.OAuth2 Proxy 10.Velero 11.Terraform 12.User Modules Container Platform User Guide 1.Deploy your first App 2.Concepts a. What is a <Product Name>? b. How is it Secured? c. How is it developed? (Continuous Delivery) d. Everything as Code (ArgoCD, Terraform) 3.How To a. Deploy Apps (GitLab CI, ArgoCD) b. Connect to the Platform (CLI) c. Monitor Applications (Prometheus) d. Expose Applications (Traefik, OAuth2) e. Setup Automatic Backups (Velero) f. Add a Database (Terraform, User Modules)
13. Know your Audience Use appropriate Structure Use fitting Language
14. Diátaxis “A systematic approach to technical documentation authoring.” “Diátaxis solves problems related to documentation content (what to write), style (how to write it) and architecture (how to organise it).” Diátaxis is the work of Daniele Procida, Director of Engineering at Canonical 14 QAware Know your Audience
15. Diátaxis - Tutorial • A tutorial is an experience that takes place under the guidance of a tutor. A tutorial is always learning-oriented. • don’t try to teach, Give your learner things to do, through which they can learn. • 10 key principles: ◦ Deliver visible results early and often ◦ Point out what the learner should notice ◦ Ignore options and alternatives • Example Style: We… The first-person plural affirms the relationship between tutor and learner: you are not alone; we are in this together. • Example: Kubernetes The Hard Way 15 QAware
16. Diátaxis - How-to Guide • How-to guides are directions that guide the reader through a problem or towards a result. How-to guides are goal-oriented. • A how-to guide serves the work of the already-competent user, whom you can assume to know what they want to do, and to be able to follow your instructions correctly. • 6 key principles: ◦ Address real-world complexity ◦ Provide a set of instructions ◦ Describe a logical sequence • Example Style: If you want x, do y. To achieve w, do z. Use conditional imperatives. • Example: Kubeadm Upgrade 16 QAware
17. Diátaxis - Reference Guide • Reference guides are technical descriptions of the machinery and how to operate it. • Reference material is information-oriented. • 4 key principles: ◦ Describe and only describe ◦ Adopt standard patterns ◦ Provide examples • Example Style: Django’s default logging configuration inherits Python’s defaults. It’s available as django.utils.log.DEFAULT_LOGGING and defined in django/utils/log.py State facts about the machinery and its behaviour. • Example: Kubernetes API 17 QAware
18. Diátaxis - Explanation • Explanation is a discursive treatment of a subject, that permits reflection. • Explanation is understanding-oriented. • 5 key principles: ◦ Provide context ◦ Talk about the subject ◦ Admit opinion and perspective • Example Style: An x interacts with a y as follows: … Unfold the machinery’s internal secrets, to help understand why something does what it does. • Example: Kubernetes Components / Why Kubernetes / Historical Context 18 QAware
19. 19 QAware Typical Audiences in Software Projects Developers Architects Users
20. Key Learning: Use appropriate Structure
21. Every Product needs Documentation Imagine assembling furniture without a manual. 21 QAware
22. “All you ever need to construct, communicate and document your software architecture. Proven, practical and pragmatic. Free and open source, takes the pain out of documentation.” The answer to everything regarding your architecture 😉. arc42 22 QAware Structure for Architecture (Explanation)
23. arc42 23 QAware
24. arc42 24 QAware
25. arc42 25 QAware
26. arc42 26 QAware
27. arc42 27 QAware
28. arc42 28 QAware
29. arc42 29 QAware
30. • always know what to write • never forget something • structure is familiar over time 30 QAware arc42 is cool
31. Key Learning: Use fitting Style
32. Google Developer Documentation Style • Intention: Standardized and clear Google documentation • Philosophy: Guidelines, not rules. • Highlights: ◦ Tone and content ◦ Language and grammar ◦ Formatting, punctuation, and organization ◦ Images 32 QAware
33. Google Developer Documentation Style 33 QAware
34. Google Developer Documentation Style 34 QAware
35. Google Developer Documentation Style 35 QAware
36. Google Developer Documentation Style 36 QAware
37. Summary: Clean Documentation Clean Package Structure Convention over Configuration Domain Driven Design Clean Code Open / Inner Source 37 QAware Structure by Audience (Diataxis) Standardize Structure (arc42) Use domain language Simple language Open / Inner Source Software Engineering Clean Documentation
38. What tools are there to help us build awesome documentation?
39. Vale.sh — Lint your docs • Checks the written text, not the raw text document • Check if your docs comply with established style guides • Automate it — just like code • Find typos and inconsistencies • Check against your own vocab • Integrations for IntelliJ, VSCode and CI • Highly extendible • Predefined established styles • Used by many companies 39 QAware
40. Predefined styles 40 QAware
41. Predefined styles 41 QAware Just trust Google!
42. 42 QAware Vale.sh — CLI
43. Vale.sh — GitHub Actions 43 QAware
44. Key Learning: Lint your docs
45. 45 QAware Which markup (language) should I use? AsciiDoc
46. Why should you use AsciiDoc? • Widespread support (e.g. IntelliJ and GitLab) • It hits the sweet-spot between simplicity and control ◦ Markdown ▪ Too simple 🦧 ▪ multiple flavours 🍇 ◦ LaTeX ▪ Too complex 🔭 ▪ infinite number of flavours ❄ ◦ AsciiDoc ▪ Just right 👌 ▪ One standard 👌 46 QAware
47. AsciiDoc killer features 47 QAware
48. AsciiDoc killer features • Modularity — Works well with multiple files • TOC — Table of contents is a built-in feature • References — Titles and explicit anchors can be used as ref-targets • Tables — Easier to build than in Markdown, but still more powerful • Examples — Easily show code examples (and explain it with …) • Code Callouts — Explaining code is very easy • Collapsibles — Built-in feature to expand content • Element Titles — Images, examples, etc. can have titles 48 QAware
49. Key Learning: Try AsciiDoc
50. README.adoc GitLab and GitHub accept README.adoc’s (beside README.md’s)! Just use it 😉 50 QAware
51. Start small A README.adoc is all you need to start your journey to a great documentation! 51 QAware = My project // Tell me what is the project about == Installation // How can I install/use it == Configuration // What do I need to configure to use it == Contribute // How can I contribute?
52. Grow as you go As your README.adoc grows with content you want to split it up: • README.adoc ⇒ Short (marketing) intro and links to the real docs • docs/user.adoc ⇒ Docs that will be read most often. Written for the actual users. • docs/developer.adoc ⇒ Docs written for developers of the project. • docs/architecture.adoc ⇒ A reference to understand the architecture and decisions made. 52 QAware
53. Final stage: Modules As your project scales the documentation grows. To maintain a very good UX when accessing the docs Modules helps to structure and display your content. Caveat: Things get harder to find as the amount of documentation grows. 53 QAware
54. 54 QAware How can I manage modularized documentation at scale?
55. What is antora? The single or multi-repository documentation site generator for tech writers who 💜 writing in AsciiDoc. 55 QAware
56. Why should I use Antora? Projects at scale require excellent tooling • Client-side search easy to provide ⇒ make things easy to find (again) • Supports multiple revisions of the same module (eg. 3.x and 4.x) • Modules can be placed in different repos • IDE support is very good • Integrates Kroki as single code to image render dependency • Possibly the best tool to build a documentation hub 56 QAware
57. My proposal https://github.com/qaware/clean-documentation-template 57 QAware
58. Key Learning: Grow step by step
59. qaware.de QAware GmbH Mainz Rheinstraße 4 C 55116 Mainz Tel. +49 6131 21569-0 info@qaware.de linkedin.com/company/qaware-gmbh xing.com/companies/qawaregmbh slideshare.net/qaware github.com/qaware Q&A
60. 60 QAware
61. 61 QAware
62. 62 QAware
63. 63 QAware
64. 64 QAware