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
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
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
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
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
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
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
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
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.
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 |===
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
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 }
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
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
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
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
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"}
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)
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']
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
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
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
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 ); }
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
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
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)
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, …)?
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
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
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
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
32. Examples 1. http://beanvalidation.org/ Beanvalidation Spec 2.0 © msg | November 2017 | Continuous Lifecycle Mannheim | Continuous Delivery for your Documentation | Alexander Schwartz 35
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