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

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 

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 

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 

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 

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 

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 

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 

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. 

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 |=== 

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 

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 } 

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 

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 

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 

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 

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"} 

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) 

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'] 

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

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 

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 

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 ); } 

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 

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 

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) 

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

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 

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 

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 

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 

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

.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