Documentation is Dead, Long Live Documentation!

Transcript

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

   View Slide

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

   View Slide

3. 3
   #GitLabCommit
   The daily disaster
   with documentation
   

   View Slide

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?
   

   View Slide

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
   

   View Slide

6. 6
   #GitLabCommit
   Our
   dreamworld
   

   View Slide

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
   

   View Slide

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
   

   View Slide

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
   

   View Slide

10. 10
    #GitLabCommit
    Explore new tools
    for documentation
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide

14. 14
    #GitLabCommit
    Setup
    in GitLab
    

    View Slide

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
    

    View Slide

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

    View Slide

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
    

    View Slide

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
    

    View Slide

19. 19
    #GitLabCommit
    Wrap up with live
    demo
    

    View Slide

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

    View Slide