Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

3 #GitLabCommit The daily disaster with documentation

Slide 4

Slide 4 text

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?

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

6 #GitLabCommit Our dreamworld

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

10 #GitLabCommit Explore new tools for documentation

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

14 #GitLabCommit Setup in GitLab

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

17 #GitLabCommit #GitLabCommit Neat to know #1 integration ● Just pick a GitLab Repository as storage ● Save the ● Add image to the doc

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

19 #GitLabCommit Wrap up with live demo

Slide 20

Slide 20 text

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