Solutions for when documentation fails
•
3 likes•936 views
The document discusses solutions for when documentation avoidance fails. It recommends using plain text formats like Markdown or AsciiDoc to write documentation, keeping documentation and code together, integrating documentation into development processes using tools like Git, Maven and Docker, and automating documentation testing and generation as much as possible. The document provides examples of using Arquillian, Maven, AShot and Graphene to automate the creation of a user manual with screenshots from automated tests. The goal is to produce an up-to-date user manual with high test coverage through continuous integration of documentation with code.
Recommended
More Related Content
What's hot
What's hot (12)
Similar to Solutions for when documentation fails
Similar to Solutions for when documentation fails (20)
More from Martijn Dashorst
More from Martijn Dashorst (20)
Recently uploaded
Recently uploaded (20)
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
- 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 : : : : : : : : : : :
- 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,
- 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
- 27. WIKIs nobody got fired for buying atlassian
- 28. WIKIs are where documentation goes to die – Joseph Wilk
- 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
- 36. PLAIN TEXT OPTIONS markdown docbook asciidoctor DITAA HTML# # #
- 37. 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
- 38. FIRST THERE WAS MARKDOWN Markdown(John Gruber) http://daringfireball.net/projects/markdown
- 39. THEN THERE WAS MARKDOWN Markdown Github Flavored Markdown Extra MultiMarkdown (John Gruber)
- 40. THEN THERE WAS MARKDOWN Markdown Github Flavored Markdown Extra MultiMarkdown CommonMark https://xkcd.com/927/
- 41. 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
- 42. ASCIIDOCTOR + Table of contents + Output to epub, pdf, html, docbook + Bibliography + Footnotes + Macros + Substitutions
- 45. PLAIN TEXT CHOICES markdown asciidoctor README:1 EVERYTHING ELSE: 1 github does support README.adoc using asciidoctor format
- 46. 1. docs → git 2. docs → build tools 3. docs → deployment tools
- 48. 1. docs → git 2. docs → build tools 3. docs → deployment tools
- 50. result
- 51. WHAT IF WE COULD USE DEV TOOLS FOR A USER MANUAL?
- 52. text and screenshots USER MANUAL:
- 53. text and screenshots USER MANUAL:
- 55. I have made this longer than usual because I have not had time to make it shorter.
- 56. I have made this longer than usual because I have not had time to make it shorter.
- 57. 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
- 58. «intentionally left blank for dramatic purposes»
- 59. UP-TO-DATE USER MANUAL CASE STUDY
- 60. Identity & access management - 2FA for critical infrastructure - Localized authorization - 4 eyes principle - Installs as software appliance - Web App - Native mobile apps
- 61. vaults for secure team shares4 eyes principle
- 63. the 85 pages are written in asciidoc, converted using asciidoctor(all text is written by a human)
- 64. the 88 screenshots are captured during testing, achieving 90% code coverage
- 65. 100%automated
- 66. arquillian maven mavenaShotgraphene TOOLS USED FOR DOCUMENTATION
- 68. a functional, integration and acceptance test platform http://arquillian.org/
- 69. modules a functional, integration and acceptance test platform http://arquillian.org/ deploymentcontainers packaging injection
- 71. Captures screenshot on test failure with Arquillian Recorder http://arquillian.org/ recording
- 72. 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() { }
- 73. @RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser; @Test public void step1LogIn() { } } Anatomy of a test case 1 3 2
- 74. @RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser; @Test public void step1LogIn() { } } Anatomy of a test case 1 3 2
- 75. @RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser; @Test public void step1LogIn() { } } Anatomy of a test case 1 3 2
- 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. @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
- 82. a wrapper for Selenium/ WebDriver graphenehttp://arquillian.org/arquillian-graphene/
- 83. Page Objects encapsulate requests and HTML https://martinfowler.com/bliki/PageObject.html
- 85. browser .navigate() .to("https://test.com/login"); Using Page Objects LoginPage loginPage = Graphene.goTo(LoginPage.class);
- 88. 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
- 90. WebDriver Screenshot utility. Take screenshots, crop, prettify, compare. aShothttps://github.com/yandex-qatools/ashot
- 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. 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. 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
- 96. Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2
- 97. Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username"))); Screenshot Composition 1 3 2 requires JQuery intarget page
- 98. Screenshot screenshot = new AShot() .imageCropper(new IndentCropper(50)) .takeScreenshot(browser, browser.findElement( By.id("username"))); 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
- 100. new AShot().takeScreenshot(browser, browser.findElements( ByJQuery.selector( "input[name='username'], a:contains('Sign in')"))); Screenshot Composition 1 3 2 PLURAL!
- 106. graphene aShotarquillian ++ = screenshots Maven module: keyhub-tests
- 107. maven maven + = screenshots maven test module
- 112. THE RESULT
- 113. THE RESULT
- 116. $
- 117. $ %
- 118. $ % &
- 120. 1. use plain text 2. keep code and docs together 3. integrate docs into your dev process 4. automate all the things
- 122. THANK YOU! @dashorst
- 123. QUESTIONS? @dashorst