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

Continuous Delivery for your Documentation

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.

Alexander Schwartz

November 15, 2017
Tweet

More Decks by Alexander Schwartz

Other Decks in Technology

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
    [email protected]
    @ahus1de
    msg systems ag (Headquarters)
    Robert-Buerkle-Str. 1, 85737 Ismaning
    Germany
    www.msg-systems.com

    View Slide