1 #GitLabCommit #GitLabContribute Documentation is dead, long live documentation

2 #GitLabCommit Phil(ipp Westphalen) Software Engineer, BLUME2000 AG @Phil404 @Koala_Phil Bene(dikt Stemmildt) CIO, BLUME2000 AG @beneStem @slashBene

3 #GitLabCommit The daily disaster with documentation

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 #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 #GitLabCommit Our dreamworld

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 #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 #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 #GitLabCommit Explore new tools for documentation

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 #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 #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 #GitLabCommit Setup in GitLab

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 #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 #GitLabCommit #GitLabCommit Neat to know #1 draw.io integration ● Just pick a GitLab Repository as storage ● Save the ● Add image to the doc

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 #GitLabCommit Wrap up with live demo

20 #GitLabCommit Thank you Documentation is dead, long live documentation