Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documentation is Dead, Long Live Documentation!

Documentation is Dead, Long Live Documentation!

6be82529683c6bdee1fcda3f7ff783f0?s=128

Benedikt Stemmildt

March 25, 2022
Tweet

More Decks by Benedikt Stemmildt

Other Decks in Technology

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