Documentation is Dead, Long Live Documentation!

Transcript

1. 1 #GitLabCommit #GitLabContribute Documentation is dead, long live documentation
2. 2 #GitLabCommit Phil(ipp Westphalen) Software Engineer, BLUME2000 AG @Phil404 @Koala_Phil Bene(dikt Stemmildt) CIO, BLUME2000 AG @beneStem @slashBene
3. 3 #GitLabCommit The daily disaster with documentation
4. 4 #GitLabCommit #GitLabCommit PO view • What the heck! • No structure at all • It's hard to motivate anyone to write in that “editor” • Comfort zone, but why?
5. 5 #GitLabCommit 5 Dev view • Writing documentation feels dull, boring and like a waste of time • I have this powerful godlike writing tool called IDE and must leave it? • It is much harder than writing code
6. 6 #GitLabCommit Our dreamworld
7. 7 #GitLabCommit Our dreamworld • Lightweight documentation tool • Easy to write good looking docs • Focus on creating content not layout • Should give structure and guidance • Finding stuff in the docs should be effortless • Fun to write and read the documentation
8. 8 #GitLabCommit Requirements • Simple writing in a common language • Essential writing features like links, pictures, etc. • Advanced writing features like admonitions, code blocks, etc. • Essential tool features like search and navigation • Accessible via Web and IDE • Means to integrate decentralized documentations into one • Live feedback while writing • Maintaining and running it should be effortless
9. 9 #GitLabCommit A word of caution on generating documentation It is all about the purpose • Think about the audience • It is like code: ◦ You don’t write pretty code for the machine ◦ You write it for other developers! • Only generate it when appropriate
10. 10 #GitLabCommit Explore new tools for documentation
11. 11 #GitLabCommit #GitLabCommit VuePress • Static Code Generation build on Vue.js (typescript) • Write docs in markdown ◦ Even POs can code that ;) ◦ Well known • Simple and fast
12. 12 #GitLabCommit 12 Material for MkDocs • Static Code Generation build on MkDocs (python) • Write docs in markdown ◦ Even POs can code that ;) ◦ Well known • Advanced and fast
13. 13 #GitLabCommit VuePress vs. MkDocs Material for MkDocs + Easy setup + Known programming language + Markdown + Very mature + A ton of features + Powerful search - Insider Version not for free but a very well designed open source strategy VuePress + Easy setup + Known programming language + Markdown - Fairly new player - Only basic functionality - Search only in headlines (fixed with v2) + Free
14. 14 #GitLabCommit Setup in GitLab
15. 15 #GitLabCommit Mkdocs setup Just a small configuration and a pip install • Setup mkdocs • Install via pip • Write the configuration file ◦ Navigation is also written there • Serve and build is done via ◦ mkdocs serve ◦ mkdocs build
16. 16 #GitLabCommit Directory structure Directory structure equals the navigation concept • Structure the documentation by directories • Easy to navigate and extend • Everything is stored there ◦ Even images (maybe a problem later?)
17. 17 #GitLabCommit #GitLabCommit Neat to know #1 draw.io integration • Just pick a GitLab Repository as storage • Save the • Add image to the doc
18. 18 #GitLabCommit Setup with GitLab Pages Quite easy to deploy! • We host our documentation on GitLab Pages • It is accessible via a custom domain and protected by the GitLab login • We use review apps for bigger changes
19. 19 #GitLabCommit Wrap up with live demo
20. 20 #GitLabCommit Thank you Documentation is dead, long live documentation