Continuous Delivery for your Documentation

This talk gives an overview of the tools to put the documentation you create into your build. Use it to document Text, APIs, Diagrams, Tests, Code Snippets, etc.

Transcript

1. .consulting .solutions .partnership
   Continuous Delivery for your Documentation
   Alexander Schwartz, Principal IT Consultant
   Continuous Lifecycle Mannheim – November 14th 2017
   

   View Slide

2. Continuous Delivery for your Documentation
   2
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
   Motivation
   1
   Technologies
   2
   • Text
   • Diagrams
   • APIs
   • Tests
   Challenges and Choices
   3
   Examples
   4
   

   View Slide

3. Continuous Delivery for your Documentation
   3
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
   Motivation
   1
   Technologies
   2
   • Text
   • Diagrams
   • APIs
   • Tests
   Challenges and Choices
   3
   Examples
   4
   

   View Slide

4. Tool + –
   Office-Suite
   Motivation
   What do you use to write your docs?
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 4
   

   View Slide

5. Tool + –
   Office-Suite
   Wiki
   Motivation
   What do you use to write your docs?
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 5
   

   View Slide

6. Motivation
   What to aim for in a Continuous Integration/Delivery setup
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 6
   Code Snippets
   Publish result
   (to website) Printable
   Documentation
   Track Changes
   Search
   Documentation
   De-Duplication
   and Re-Use
   Text
   Code Fragments
   APIs
   Diagrams
   Tests
   Share Merge
   

   View Slide

7. Areas for a BoF Treat Documentation like Code
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 7
   Topics
   Technologies for Text, APIs, Tests, Diagrams Challenges and Choices
   Examples
   Markdown AsciiDoc
   Graphiz/Dot
   PlantUML
   JGiven RAML
   Swagger
   OpenAPI
   XSD/WSDL
   Spring REST Doc
   Write more tests or
   more documentation?
   API documentation
   from Code, Contract or Tests?
   Separate Code Base
   for Documentation? How to integrate
   non-tech contributors?
   Spell- and Grammar
   checking?
   Highlight changes
   in versions?
   Cucumber
   Vert.x Docs Spring Boot Docs
   Asciidoctor
   Saltstack Docs
   Gitbook
   Bean Validation 2.0 Spec
   Graylog
   reStructuredText
   

   View Slide

8. Continuous Delivery for your Documentation
   8
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
   Motivation
   1
   Technologies
   2
   • Text
   • Diagrams
   • APIs
   • Tests
   Challenges and Choices
   3
   Examples
   4
   

   View Slide

9. Text
   Markdown
   © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 9
   Pro
   • Intuitive Text format
   • Easy to start
   Con:
   • Missing the full O‘Reilly/DocBook feature set
   • Different flavours of Markdown syntax
   • Different generators for HTML/PDF output
   # Title
   ## Headline
   Normal text. **Bold**,
   _italic_ and `monospace`.
   Empty lines separate
   paragraphs.
   

   View Slide

10. Text
    Asciidoc
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 10
    Pro
    • Intuitive Text format
    • Full O‘Reilly/Docbook featureset
    • Very good support for tables and
    to include source code from live code
    • Asciidoctor Implementation supports
    HTML, DocBook and PDF output
    • Includes for files
    Con:
    • Moderate PDF styling available
    [source,txt]
    .Name of the file
    ----
    This is a listing with
    highlighting
    ----
    [cols="2*", options="header"]
    |===
    |Heading
    |Another heading
    |Text in first column
    |Text in second column
    |===
    

    View Slide

11. Continuous Delivery for your Documentation
    11
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
    Motivation
    1
    Technologies
    2
    • Text
    • Diagrams
    • APIs
    • Tests
    Challenges and Choices
    3
    Examples
    4
    

    View Slide

12. Text
    Graphiz/DOT
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 12
    Pro
    • More flexible than PlantUML
    • Can be rendered via PlantUML
    pipeline
    Con:
    • Still auto layout can get messy
    digraph foo {
    node [style=rounded]
    node1 [shape=box]
    node2 [fillcolor=yellow,
    style="rounded,filled",
    shape=diamond]
    node3 [shape=record,
    label="{ a | b | c }"]
    node1 -> node2 -> node3
    }
    

    View Slide

13. Text
    PlantUML
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 13
    Pro
    • Sequence Diagram
    • State Diagram
    • Activity-Diagrams
    (even with swim lanes)
    Con:
    • Component and Deployment Diagrams
    (can get messy if you have lots
    of items due to auto-layout)
    start
    :Hello world;
    :This is on defined on
    several **lines**;
    stop
    [Component] --> Interface1
    [Component] -> Interface2
    

    View Slide

14. Continuous Delivery for your Documentation
    14
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
    Motivation
    1
    Technologies
    2
    • Text
    • Diagrams
    • APIs
    • Tests
    Challenges and Choices
    3
    Examples
    4
    

    View Slide

15. APIs
    Docs from Implementation
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 15
    Pro
    • Up to date with Implementation
    • Implementation: for example OpenAPI aka Swagger (swagger-doclet)
    Generated outputs:
    • Live-API, AsciiDoc Output, …
    Cons
    • Additional annotations necessary for complex return types
    • Changes in Implementation might break agreed API
    

    View Slide

16. APIs
    Docs from Contracts
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 16
    Pro
    • Writing technical specs is approachable to non-developers
    • Formats include: RAML, Swagger, OpenAPI, WSDL
    • Tests can check if they are compliant with the spec (see nidi3’s RAML Tester)
    Generated outputs:
    • HTML from WSDLs (using XS3P)
    • HTML from RAML
    • Live API for Swagger
    Cons
    • Swagger/RAML/OpenAPI don’t work for Hypermedia
    

    View Slide

17. APIs
    RAML Example
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 17
    YAML files to describe resources (with parameters, examples, JSON Schema, etc.)
    /books:
    /{bookTitle}
    get:
    queryParameters:
    author:
    displayName: Author
    type: string
    description: An author's full name
    example: Mary Roach
    required: false
    /{songId}:
    description: Song entity
    get:
    description: Get the song with `songId = {songId}`
    responses:
    200:
    ...
    404:
    body:
    application/json:
    example: |
    {"message": "Song not found"}
    

    View Slide

18. APIs
    Docs from Test Cases
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 18
    Pro
    • Up to date with Implementation
    • Provides a step-by-step and how-to guide
    • Implementation: Spring REST Docs
    Generated outputs:
    • Online Documentation (Asciidoctor)
    Cons
    • Can’t be written by non-technical people, can’t be written in advance
    (Possible Solution: hand-written spec before implementation, step-by-step replacement as part of the
    implementation)
    

    View Slide

19. APIs
    Spring REST Doc
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 19
    Test case plus Documentation Stub…
    this.mockMvc.perform(get("/notes"))
    .andExpect(status().isOk())
    .andDo(document("notes-list-example",
    links(
    linkWithRel("self")
    .description("Canonical link for this resource"),
    linkWithRel("profile")
    .description("The ALPS profile ...")),
    responseFields(
    subsectionWithPath("_embedded.notes")
    .description("An array of ..."),
    subsectionWithPath("_links")
    .description("... to other resources"))));
    [[resources-notes-list]]
    === Listing notes
    A `GET` request will list all of the service's notes.
    operation::notes-list-example
    [snippets='response-fields,
    curl-request,http-response,links']
    

    View Slide

20. APIs
    Spring REST Doc
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 20
    Documentation Stub
    Generated from Test case
    

    View Slide

21. Continuous Delivery for your Documentation
    21
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
    Motivation
    1
    Technologies
    2
    • Text
    • Diagrams
    • APIs
    • Tests
    Challenges and Choices
    3
    Examples
    4
    

    View Slide

22. Tests
    1. http://jgiven.org/
    JGiven
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 22
    Pro
    • Write test cases as Java Code
    • Test reports readable by business owners
    • Developers understand the intention of a test (even when some other developer created it)
    • Refactoring of tests using IDE
    • Searchable HTML report, parse able JSON output.
    Con:
    • Can only be written by developer
    (but Given-When-Then test case can be part of the spec/user story provided by business)
    • Additional annotations and more code in your test cases
    

    View Slide

23. Tests
    1. http://jgiven.org/
    JGiven
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 23
    @Test
    @FeatureAttachments
    public void attachments_appear_in_the_HTML5_report() throws Exception {
    String content = "Some Example Attachment\nwith some example content";
    given().a_report_model()
    .and().step_$_of_scenario_$_has_a_text_attachment_with_content( 1, 1, content );
    jsonReports
    .and().the_report_exist_as_JSON_file();
    whenReport
    .and().the_HTML_Report_Generator_is_executed();
    when().the_page_of_scenario_$_is_opened( 1 );
    then().an_attachment_icon_exists()
    .and().the_content_of_the_attachment_referenced_by_the_icon_is( content );
    }
    

    View Slide

24. Continuous Delivery for your Documentation
    24
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
    Motivation
    1
    Technologies
    2
    • Text
    • Diagrams
    • APIs
    • Tests
    Challenges and Choices
    3
    Examples
    4
    

    View Slide

25. Choice
    Where to place the documentation? In the code base or external?
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 25
    Pro one project:
    • code and documentation are tagged/branched in a single commit
    • Easier code review
    • Inclusion of diagrams from code and code snippets
    Pro multiple projects:
    • Documentation needs to be ready once the you release the software
    • Every documentation change triggers a build and possibly also a deployment
    • A bug fix for the documentation will lead to a release of your software
    

    View Slide

26. Choice
    Should devs focus on documentation, or clearer tests?
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 26
    Usually you want to keep your software to be evolvable.
    This (among others) requires a reasonable amount of tests and documentation.
    • Too many, too few or the wrong tests can be a burden – the same is true for documentation.
    • Do you know what parts of your documentation you write is actually read by someone else?
    • Who is in the audience? Describe in the first paragraph who you are writing this document for!
    • What kind of additional documentation will make you faster? (example: train new team members)
    • Is there something you can automate, so you can afterwards delete the documentation for the manual
    process?
    • Are tests a kind of documentation? (especially BDD tests for business stakeholders)
    

    View Slide

27. Challenges
    How to integrate non-tech contributors?
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 27
    Asciidoctor/Markdown
    • Use a simple IDE like i.e. AsciidocFX (stand-alone editor?)
    • Use GitBook editor?
    Diagrams (SVG)
    • Use yEd as it has a better User Interface?
    • Alternatives to PlantUML with less autolayout?
    API
    • Anything that supports contract first (RAML, XSD, JSON Schema, …)?
    

    View Slide

28. Continuous Delivery for your Documentation
    31
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz
    Motivation
    1
    Technologies
    2
    • Text
    • Diagrams
    • APIs
    • Tests
    Challenges and Choices
    3
    Examples
    4
    

    View Slide

29. Examples
    1. http://asciidoctor.org/docs/asciidoc-writers-guide/
    Asciidoctor’s Writers guide
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 32
    

    View Slide

30. Examples
    1. http://docs.spring.io/spring-boot/docs/1.5.3.RELEASE/reference/htmlsingle/
    Spring Boot Reference Guide
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 33
    

    View Slide

31. Examples
    1. https://docs.saltstack.com/en/latest/topics/installation/index.html
    Saltstack
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 34
    

    View Slide

32. Examples
    1. http://beanvalidation.org/
    Beanvalidation Spec 2.0
    © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 35
    

    View Slide

33. .consulting .solutions .partnership
    Alexander Schwartz
    Principal IT Consultant
    +49 171 5625767
    alexander.schwartz@msg-systems.com
    @ahus1de
    msg systems ag (Headquarters)
    Robert-Buerkle-Str. 1, 85737 Ismaning
    Germany
    www.msg-systems.com
    

    View Slide