Solutions for when documentation fails

1. SOLUTIONS FOR WHEN DOCUMENTATION AVOIDANCE MARTIJN DASHORST TOPICUS FAILS

2. MARTIJN DASHORST TOPICUS  PARNASSYS, SOMTODAY, EDUARTE, ZIEN!VO, IRIS+,TEACHER, CONFERENCE ORGANIZER ENGINEER  JAVA, DOCKER, ECLIPSE, MAVEN, WICKET HOBBIES  LEGO, STAR TREK, STAR WARS, PODCASTS @DASHORST

3. LET'S DISCUSS THE RELATIONSHIP  BETWEEN DEVELOPERS AND DOCUMENTATION

4. WHO USES DOCUMENTATION?✋

5. CHALLENGES AT WORK STACKOVERFLOW DEVELOPER SURVEY 2016

6. CHALLENGES AT WORK TRYING TO BE NICE 8% 12% STACKOVERFLOW DEVELOPER SURVEY 2016

7. CHALLENGES AT WORK TRYING TO BE NICE POOR INFRASTRUCTURE 8% 12% STACKOVERFLOW DEVELOPER SURVEY 2016

8. STACKOVERFLOW DEVELOPER SURVEY 2016 CHALLENGES AT WORK TRYING TO BE NICE POOR INFRASTRUCTURE UNSPECIFIC SPECIFICATIONS : : : : : : : : : : : : : : : : : : : : : : 8% 12% 34% 35% 35%

9. STACKOVERFLOW DEVELOPER SURVEY 2016 CHALLENGES AT WORK TRYING TO BE NICE POOR INFRASTRUCTURE UNSPECIFIC SPECIFICATIONS : : : : : : : : : : : POOR DOCUMENTATION UNREALISIC EXPECTATIONS : : : : : : : : : : : 8% 12% 34% 35% 35%

10. IMPORTANT FACTORS IN APIs PROGRAMMABLE WEB  SURVEY  2013 PRICE : : : : : : : : : : :

11. IMPORTANT FACTORS IN APIs PROGRAMMABLE WEB  SURVEY  2013 SERVICE RESPONSIVENESS/PERFORMANCE SERVICE AVAILABLITY/UPTIME : : : : : : : : : : : PRICE : : : : : : : : : : :

12. IMPORTANT FACTORS IN APIs PROGRAMMABLE WEB  SURVEY  2013 SERVICE RESPONSIVENESS/PERFORMANCE SERVICE AVAILABLITY/UPTIME COMPLETE AND ACCURATE DOCUMENTATION : : : : : : : : : : : PRICE : : : : : : : : : : :

13. WHO WRITES DOCUMENTATION?✋

14. WHO ENJOYS IT?✋

15. IT'S COMPLICATED

16. The lack of documentation  can lead to meetings – Peter Hilton

17. JFALL 2016

18. LEAVE YOUR PHONE# IN EVERY SOURCE FILE JUST-IN-TIME DOCUMENTATION WRITE GREAT CODE, COMMENT IT WRITE JUST ENOUGH DOCS, BUT NOT MORE

19. CASES WHEN DOCUMENTATION AVOIDANCE FAILS user manual api guide onboarding guide code comments design docs ...

20. everywhere a user meets development YOU NEED DOCUMENTATION

21. everywhere a user meets development YOU NEED DOCUMENTATION a new team member is a user ALSO,

22. OPTIONS FOR WRITING DOCUMENTATION

23. CODE good naming good structure comments javadocis documentation up-to-date

24. CODEas documentation fails when > 30k good naming good structure comments javadoc up-to-date

25. JAVADOC good for APIs use overview.html use package.html no stupid javadoc up-to-date

26. *drive google microsoft  icloud sharepoint "f-share"

27. WIKIs nobody got fired for buying atlassian

28. WIKIs are where documentation goes to die – Joseph Wilk

29. CODE and JAVADOC mostly up-to-date

30. CODE and JAVADOC and DOCS up-to-date?

31. WHAT IF WE COULD USE DEV TOOLS FOR DOCUMENTATION? git maven jenkins docker

32. 1. docs → git 2. docs → build tools 3. docs → deployment tools

33. GIT ❤ TEXT FILES

34. PLAIN TEXT OPTIONS markdown docbook asciidoctor DITAA HTML

35. PLAIN TEXT OPTIONS markdown docbook asciidoctor DITAA HTML# # #

36. MARKDOWN + light weight + easy to write + easy to read - limited A First Level Header ==================== A Second Level Header --------------------- Now is the time for all good men to come to the aid of their country. This is just a regular paragraph. The quick brown fox jumped over the lazy dog's back. ### Header 3 > This is a blockquote. > > This is the second paragraph in the blockquote. > > ## This is an H2 in a blockquote

37. FIRST THERE WAS MARKDOWN Markdown(John Gruber) http://daringﬁreball.net/projects/markdown

38. THEN THERE WAS MARKDOWN Markdown Github Flavored Markdown Extra MultiMarkdown (John Gruber)

39. THEN THERE WAS MARKDOWN Markdown Github Flavored Markdown Extra MultiMarkdown CommonMark https://xkcd.com/927/

40. ASCIIDOCTOR + medium weight + easy to write + easy to read + comprehensive + maven support + 1 version # A First Level Header ## A Second Level Header Now is the time for all good men to come to the aid of their country. This is just a regular paragraph. The quick brown fox jumped over the lazy dog's back. ### Header 3 > This is a blockquote. > > This is the second paragraph in the blockquote. > > ## This is an H2 in a blockquote

41. ASCIIDOCTOR + Table of contents + Output to epub, pdf, html, docbook + Bibliography + Footnotes  + Macros  + Substitutions

42. ASCIIDOCTOR + file inclusions: [source,java] ---- include::org/asciidoctor/Asciidoctor.java[lines=5..10] ----

43. ASCIIDOCTOR + code callouts [source,xml] ---- include::pom.xml ---- <1> Adds Arquillian Cube <2> From the point of view

44. PLAIN TEXT CHOICES markdown asciidoctor README:1 EVERYTHING ELSE: 1 github does support README.adoc using asciidoctor format

46. maven maven + guide.html guide.pdf =

48. guide.pdf + guide.html =+ maven mavendockerhttpd profit

49. result

50. WHAT IF WE COULD USE DEV TOOLS FOR A   USER MANUAL?

51. text and screenshots USER MANUAL:

52. text and screenshots USER MANUAL:

53. screenshots considered harmful

54. I have made this longer than usual because I have not had time to make it shorter.

55. I have made this longer than usual because I have not had time to make it shorter.

56. screenshots are always out-of-date Windows™ 10 Admin Guide 1. Logging in An administrator is someone who can make changes on a computer that will affect other users of the computer. Administrators can change security settings, install software and hardware, access all ﬁles on the computer, and make changes to other user accounts. To log on as an administrator, you need to have a user account on the computer with an Administrator account type. If your account type is not Administrator, then you cannot log on as an administrator unless you know the user name password for another

57. «intentionally left blank for dramatic purposes»

58. UP-TO-DATE   USER MANUAL CASE STUDY

59. Identity & access management - 2FA for critical infrastructure - Localized authorization - 4 eyes principle - Installs as software appliance - Web App - Native mobile apps

60. vaults for secure team shares4 eyes principle

61. 85PAGES 88IMAGES USER MANUAL

62. the 85 pages are written in asciidoc, converted using asciidoctor(all text is written by a human)

63. the 88 screenshots are captured during testing, achieving 90% code coverage

64. 100%automated

65. arquillian maven mavenaShotgraphene TOOLS USED FOR DOCUMENTATION

66. arquillian maven mavenaShotgraphene

67. a functional, integration  and acceptance test platform http://arquillian.org/

68. modules a functional, integration  and acceptance test platform http://arquillian.org/ deploymentcontainers packaging injection

69. webdriver http://arquillian.org/ integrationrecording wildﬂy cube tomcat etcglassﬁsh

70. Captures screenshot on test failure with Arquillian Recorder http://arquillian.org/ recording

71. Skips a test  if the issue is not done. Runs a test  if the issue is done. Closes a issue   if the test is successful http://arquillian.org/ integration @Test @Jira("ARQ-1907") public void test1() { } @Test @Github("123") public void test2() { }

72. @RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser; @Test public void step1LogIn() { } } Anatomy of a test case 1 3 2

75. @Test public void login() { browser .navigate() .to("https://test.com/login"); browser .findElement(By.name("username")) .sendKeys("bertjan"); Implement test case 1 3 2 4 5

76. @Test public void login() { browser .navigate() .to("https://test.com/login"); browser .findElement(By.name("username")) .sendKeys("bertjan"); Implement test case 1 3 2 4 5

77. browser .findElement(By.name("username")) .sendKeys("bertjan"); browser .findElement(By.name("password")) .sendKeys("schrijver"); Implement test case 1 3 2 4 5

78. browser .findElement(By.name("password")) .sendKeys("schrijver"); browser .findElement(By.id("login")) .click(); Implement test case 1 3 2 4 5

79. browser .findElement(By.id("login")) .click(); Assert.assertEquals("home", browser .findElement(By.tagName("title")) .text()); } Implement test case 1 3 2 4 5

81. a wrapper for Selenium/ WebDriver graphenehttp://arquillian.org/arquillian-graphene/

82. Page Objects encapsulate requests and HTML https://martinfowler.com/bliki/PageObject.html

83. browser .navigate() .to("https://test.com/login"); Using Page Objects

84. browser .navigate() .to("https://test.com/login"); Using Page Objects LoginPage loginPage = Graphene.goTo(LoginPage.class);

85. browser .findElement(By.name("username")) .sendKeys("bertjan"); browser .findElement(By.name("password")) .sendKeys("schrijver"); browser.findElement(By.id("login")).click(); Using Page Objects

86. browser .findElement(By.name("username")) .sendKeys("bertjan"); browser .findElement(By.name("password")) .sendKeys("schrijver"); browser.findElement(By.id("login")).click(); loginPage.login("bertjan", "schrijver"); Using Page Objects

87. WEBDRIVER @Test public void login() { browser .navigate() .to("https://test.com/login"); browser .findElement(By.name("username") .sendKeys("bertjan"); browser .findElement(By.name("password") .sendKeys("schrijver"); browser .findElement(By.id("login")) .click(); } @Test public void login() { LoginPage loginPage = Graphene.goTo(LoginPage.class); loginPage .login("bertjan", "schrijver"); } GRAPHENE

89. WebDriver Screenshot utility. Take screenshots, crop, prettify, compare. aShothttps://github.com/yandex-qatools/ashot

90. take full screenshots aShothttps://github.com/yandex-qatools/ashot

91. Screenshot screenshot = new AShot().takeScreenshot(browser); Path targetFile = Paths.get( "target/screenshots", name + ".png"); ImageIO.write( screenshot.getImage(), "png", targetFile.toFile()); Take a Screenshot 1 3 2

94. compose partials aShothttps://github.com/yandex-qatools/ashot

95. Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2

96. Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2 requires JQuery intarget page

97. Screenshot screenshot = new AShot() .imageCropper(new IndentCropper(50)) .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2

98. new AShot().takeScreenshot(browser, browser.findElements( ByJQuery.selector( "input[name='username'], a:contains('Sign in')"))); Screenshot Composition 1 3 2

99. new AShot().takeScreenshot(browser, browser.findElements( ByJQuery.selector( "input[name='username'], a:contains('Sign in')"))); Screenshot Composition 1 3 2 PLURAL!

101. keyhub-backend Maven module dependencies war

102. keyhub-tests keyhub-backend Maven module dependencies war

103. keyhub-tests keyhub-backend keyhub-manual Maven module dependencies war war

104. keyhub-tests keyhub-backend keyhub-manual keyhub-app Maven module dependencies war war

105. graphene aShotarquillian ++ = screenshots Maven module: keyhub-tests

106. maven maven + = screenshots maven test module

107. + maven maven + manual.html manual.pdf = manual.adoc maven manual module

108. + maven maven manual.war= manual.html manual.pdf maven manual module

109. application.war + manual.war =+ maven mavendockerwildfy profit maven app module

110. THE RESULT AN  UP-TO-DATE  USER MANUAL

111. THE RESULT

112. THE RESULT

113. THE RESULT 90%TEST COVERAGE

114. AUTOMATE ALL THE THINGS!

115. $

116. $ %

117. $ % &

118. SOLUTIONS FOR WHEN DOCUMENTATION AVOIDANCEFAILS

119. 1. use plain text 2. keep code and docs together 3. integrate docs into your dev process 4. automate all the things

120. writethedocs.org asciidoctor.org arquillian.org maven.apache.org sources

121. THANK YOU! @dashorst

122. QUESTIONS? @dashorst

Solutions for when documentation fails

Martijn Dashorst

Solutions for when documentation fails