Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Solutions for when documentation fails

770 views

Published on

The relationship between developers and documentation is best described as “It’s complicated”. Developers complain a lot about the lack of documentation but fail to write it themselves. How can you make writing documentation more enjoyable and use software engineering principles and tools for writing and maintaining documentation?

Join Martijn Dashorst in this session to discover how to use Git, Docker, Maven, Selenium, Asciidoctor, Markdown, Jenkins and Arquillian to make documentation more comfortable like coding. Learn how you can get a user manual with always up-to-date screenshots, and keep your code examples always compiling and tested.

Published in: Software
  • Login to see the comments

Solutions for when documentation fails

  1. 1. SOLUTIONS FOR WHEN DOCUMENTATION AVOIDANCE MARTIJN DASHORST TOPICUS FAILS
  2. 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. 3. LET'S DISCUSS THE RELATIONSHIP
 BETWEEN DEVELOPERS AND DOCUMENTATION
  4. 4. WHO USES DOCUMENTATION?✋
  5. 5. CHALLENGES AT WORK STACKOVERFLOW DEVELOPER SURVEY 2016
  6. 6. CHALLENGES AT WORK TRYING TO BE NICE 8% 12% STACKOVERFLOW DEVELOPER SURVEY 2016
  7. 7. CHALLENGES AT WORK TRYING TO BE NICE POOR INFRASTRUCTURE 8% 12% STACKOVERFLOW DEVELOPER SURVEY 2016
  8. 8. STACKOVERFLOW DEVELOPER SURVEY 2016 CHALLENGES AT WORK TRYING TO BE NICE POOR INFRASTRUCTURE UNSPECIFIC SPECIFICATIONS : : : : : : : : : : : : : : : : : : : : : : 8% 12% 34% 35% 35%
  9. 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. 10. IMPORTANT FACTORS IN APIs PROGRAMMABLE WEB
 SURVEY
 2013 PRICE : : : : : : : : : : :
  11. 11. IMPORTANT FACTORS IN APIs PROGRAMMABLE WEB
 SURVEY
 2013 SERVICE RESPONSIVENESS/PERFORMANCE SERVICE AVAILABLITY/UPTIME : : : : : : : : : : : PRICE : : : : : : : : : : :
  12. 12. IMPORTANT FACTORS IN APIs PROGRAMMABLE WEB
 SURVEY
 2013 SERVICE RESPONSIVENESS/PERFORMANCE SERVICE AVAILABLITY/UPTIME COMPLETE AND ACCURATE DOCUMENTATION : : : : : : : : : : : PRICE : : : : : : : : : : :
  13. 13. WHO WRITES DOCUMENTATION?✋
  14. 14. WHO ENJOYS IT?✋
  15. 15. IT'S COMPLICATED
  16. 16. The lack of documentation
 can lead to meetings – Peter Hilton
  17. 17. JFALL 2016
  18. 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. 19. CASES WHEN DOCUMENTATION AVOIDANCE FAILS user manual api guide onboarding guide code comments design docs ...
  20. 20. everywhere a user meets development YOU NEED DOCUMENTATION
  21. 21. everywhere a user meets development YOU NEED DOCUMENTATION a new team member is a user ALSO,
  22. 22. OPTIONS FOR WRITING DOCUMENTATION
  23. 23. CODE good naming good structure comments javadocis documentation up-to-date
  24. 24. CODEas documentation fails when > 30k good naming good structure comments javadoc up-to-date
  25. 25. JAVADOC good for APIs use overview.html use package.html no stupid javadoc up-to-date
  26. 26. *drive google microsoft
 icloud sharepoint "f-share"
  27. 27. WIKIs nobody got fired for buying atlassian
  28. 28. WIKIs are where documentation goes to die – Joseph Wilk
  29. 29. CODE and JAVADOC mostly up-to-date
  30. 30. CODE and JAVADOC and DOCS up-to-date?
  31. 31. WHAT IF WE COULD USE DEV TOOLS FOR DOCUMENTATION? git maven jenkins docker
  32. 32. 1. docs → git 2. docs → build tools 3. docs → deployment tools
  33. 33. GIT ❤ TEXT FILES
  34. 34. PLAIN TEXT OPTIONS markdown docbook asciidoctor DITAA HTML
  35. 35. PLAIN TEXT OPTIONS markdown docbook asciidoctor DITAA HTML# # #
  36. 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. 37. FIRST THERE WAS MARKDOWN Markdown(John Gruber) http://daringfireball.net/projects/markdown
  38. 38. THEN THERE WAS MARKDOWN Markdown Github Flavored Markdown Extra MultiMarkdown (John Gruber)
  39. 39. THEN THERE WAS MARKDOWN Markdown Github Flavored Markdown Extra MultiMarkdown CommonMark https://xkcd.com/927/
  40. 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. 41. ASCIIDOCTOR + Table of contents + Output to epub, pdf, html, docbook + Bibliography + Footnotes
 + Macros
 + Substitutions
  42. 42. ASCIIDOCTOR + file inclusions: [source,java] ---- include::org/asciidoctor/Asciidoctor.java[lines=5..10] ----
  43. 43. ASCIIDOCTOR + code callouts [source,xml] ---- include::pom.xml ---- <1> Adds Arquillian Cube <2> From the point of view
  44. 44. PLAIN TEXT CHOICES markdown asciidoctor README:1 EVERYTHING ELSE: 1 github does support README.adoc using asciidoctor format
  45. 45. 1. docs → git 2. docs → build tools 3. docs → deployment tools
  46. 46. maven maven + guide.html guide.pdf =
  47. 47. 1. docs → git 2. docs → build tools 3. docs → deployment tools
  48. 48. guide.pdf + guide.html =+ maven mavendockerhttpd profit
  49. 49. result
  50. 50. WHAT IF WE COULD USE DEV TOOLS FOR A 
 USER MANUAL?
  51. 51. text and screenshots USER MANUAL:
  52. 52. text and screenshots USER MANUAL:
  53. 53. screenshots considered harmful
  54. 54. I have made this longer than usual because I have not had time to make it shorter.
  55. 55. I have made this longer than usual because I have not had time to make it shorter.
  56. 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 files 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. 57. «intentionally left blank for dramatic purposes»
  58. 58. UP-TO-DATE 
 USER MANUAL CASE STUDY
  59. 59. Identity & access management - 2FA for critical infrastructure - Localized authorization - 4 eyes principle - Installs as software appliance - Web App - Native mobile apps
  60. 60. vaults for secure team shares4 eyes principle
  61. 61. 85PAGES 88IMAGES USER MANUAL
  62. 62. the 85 pages are written in asciidoc, converted using asciidoctor(all text is written by a human)
  63. 63. the 88 screenshots are captured during testing, achieving 90% code coverage
  64. 64. 100%automated
  65. 65. arquillian maven mavenaShotgraphene TOOLS USED FOR DOCUMENTATION
  66. 66. arquillian maven mavenaShotgraphene
  67. 67. a functional, integration
 and acceptance test platform http://arquillian.org/
  68. 68. modules a functional, integration
 and acceptance test platform http://arquillian.org/ deploymentcontainers packaging injection
  69. 69. webdriver http://arquillian.org/ integrationrecording wildfly cube tomcat etcglassfish
  70. 70. Captures screenshot on test failure with Arquillian Recorder http://arquillian.org/ recording
  71. 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. 72. @RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser; @Test public void step1LogIn() { } } Anatomy of a test case 1 3 2
  73. 73. @RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser; @Test public void step1LogIn() { } } Anatomy of a test case 1 3 2
  74. 74. @RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser; @Test public void step1LogIn() { } } Anatomy of a test case 1 3 2
  75. 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. 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. 77. browser .findElement(By.name("username")) .sendKeys("bertjan"); browser .findElement(By.name("password")) .sendKeys("schrijver"); Implement test case 1 3 2 4 5
  78. 78. browser .findElement(By.name("password")) .sendKeys("schrijver"); browser .findElement(By.id("login")) .click(); Implement test case 1 3 2 4 5
  79. 79. browser .findElement(By.id("login")) .click(); Assert.assertEquals("home", browser .findElement(By.tagName("title")) .text()); } Implement test case 1 3 2 4 5
  80. 80. arquillian maven mavenaShotgraphene
  81. 81. a wrapper for Selenium/ WebDriver graphenehttp://arquillian.org/arquillian-graphene/
  82. 82. Page Objects encapsulate requests and HTML https://martinfowler.com/bliki/PageObject.html
  83. 83. browser .navigate() .to("https://test.com/login"); Using Page Objects
  84. 84. browser .navigate() .to("https://test.com/login"); Using Page Objects LoginPage loginPage = Graphene.goTo(LoginPage.class);
  85. 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. 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. 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
  88. 88. arquillian maven mavenaShotgraphene
  89. 89. WebDriver Screenshot utility. Take screenshots, crop, prettify, compare. aShothttps://github.com/yandex-qatools/ashot
  90. 90. take full screenshots aShothttps://github.com/yandex-qatools/ashot
  91. 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
  92. 92. 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
  93. 93. 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. 94. compose partials aShothttps://github.com/yandex-qatools/ashot
  95. 95. Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2
  96. 96. Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2 requires JQuery intarget page
  97. 97. Screenshot screenshot = new AShot() .imageCropper(new IndentCropper(50)) .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2
  98. 98. new AShot().takeScreenshot(browser, browser.findElements( ByJQuery.selector( "input[name='username'], a:contains('Sign in')"))); Screenshot Composition 1 3 2
  99. 99. new AShot().takeScreenshot(browser, browser.findElements( ByJQuery.selector( "input[name='username'], a:contains('Sign in')"))); Screenshot Composition 1 3 2 PLURAL!
  100. 100. arquillian maven mavenaShotgraphene
  101. 101. keyhub-backend Maven module dependencies war
  102. 102. keyhub-tests keyhub-backend Maven module dependencies war
  103. 103. keyhub-tests keyhub-backend keyhub-manual Maven module dependencies war war
  104. 104. keyhub-tests keyhub-backend keyhub-manual keyhub-app Maven module dependencies war war
  105. 105. graphene aShotarquillian ++ = screenshots Maven module: keyhub-tests
  106. 106. maven maven + = screenshots maven test module
  107. 107. + maven maven + manual.html manual.pdf = manual.adoc maven manual module
  108. 108. + maven maven manual.war= manual.html manual.pdf maven manual module
  109. 109. application.war + manual.war =+ maven mavendockerwildfy profit maven app module
  110. 110. THE RESULT AN
 UP-TO-DATE
 USER MANUAL
  111. 111. THE RESULT
  112. 112. THE RESULT
  113. 113. THE RESULT 90%TEST COVERAGE
  114. 114. AUTOMATE ALL THE THINGS!
  115. 115. $
  116. 116. $ %
  117. 117. $ % &
  118. 118. SOLUTIONS FOR WHEN DOCUMENTATION AVOIDANCEFAILS
  119. 119. 1. use plain text 2. keep code and docs together 3. integrate docs into your dev process 4. automate all the things
  120. 120. writethedocs.org asciidoctor.org arquillian.org maven.apache.org sources
  121. 121. THANK YOU! @dashorst
  122. 122. QUESTIONS? @dashorst

×