solutions for when documentation fails
TRANSCRIPT
![Page 1: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/1.jpg)
SOLUTIONS FOR WHEN DOCUMENTATION
AVOIDANCE
MARTIJN DASHORST TOPICUS
FAILS
![Page 2: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/2.jpg)
MARTIJN DASHORSTTOPICUSPARNASSYS, SOMTODAY, EDUARTE, ZIEN!VO, IRIS+, TEACHER, CONFERENCE ORGANIZER ENGINEERJAVA, DOCKER, ECLIPSE, MAVEN, WICKET HOBBIESLEGO, STAR TREK, STAR WARS, PODCASTS@DASHORST
![Page 3: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/3.jpg)
LET'S DISCUSS THE RELATIONSHIP
BETWEEN DEVELOPERS AND DOCUMENTATION
![Page 4: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/4.jpg)
WHO USES DOCUMENTATION?✋
![Page 5: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/5.jpg)
CHALLENGES AT WORK
STACKOVERFLOW DEVELOPER SURVEY 2016
![Page 6: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/6.jpg)
CHALLENGES AT WORK
TRYING TO BE NICE 8%
12% STACKOVERFLOW DEVELOPER SURVEY
2016
![Page 7: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/7.jpg)
CHALLENGES AT WORK
TRYING TO BE NICE
POOR INFRASTRUCTURE
8%
12% STACKOVERFLOW DEVELOPER SURVEY
2016
![Page 8: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/8.jpg)
STACKOVERFLOW DEVELOPER SURVEY
2016
CHALLENGES AT WORK
TRYING TO BE NICE
POOR INFRASTRUCTURE
UNSPECIFIC SPECIFICATIONS
: : : : : : : : : : :
: : : : : : : : : : :
8%
12%
34%
35%
35%
![Page 9: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/9.jpg)
STACKOVERFLOW DEVELOPER SURVEY
2016
CHALLENGES AT WORK
TRYING TO BE NICE
POOR INFRASTRUCTURE
UNSPECIFIC SPECIFICATIONS
: : : : : : : : : : :
POOR DOCUMENTATION
UNREALISIC EXPECTATIONS
: : : : : : : : : : :
8%
12%
34%
35%
35%
![Page 10: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/10.jpg)
IMPORTANT FACTORS IN APIs
PROGRAMMABLE WEBSURVEY
2013
PRICE
: : : : : : : : : : :
![Page 11: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/11.jpg)
IMPORTANT FACTORS IN APIs
PROGRAMMABLE WEBSURVEY
2013
SERVICE RESPONSIVENESS/PERFORMANCE
SERVICE AVAILABLITY/UPTIME
: : : : : : : : : : :
PRICE
: : : : : : : : : : :
![Page 12: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/12.jpg)
IMPORTANT FACTORS IN APIs
PROGRAMMABLE WEBSURVEY
2013
SERVICE RESPONSIVENESS/PERFORMANCE
SERVICE AVAILABLITY/UPTIME
COMPLETE AND ACCURATE DOCUMENTATION
: : : : : : : : : : :
PRICE
: : : : : : : : : : :
![Page 13: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/13.jpg)
WHO WRITES DOCUMENTATION?✋
![Page 14: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/14.jpg)
WHO ENJOYS IT?✋
![Page 15: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/15.jpg)
IT'S COMPLICATED
![Page 16: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/16.jpg)
The lack of documentationcan lead to meetings – Peter Hilton
![Page 17: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/17.jpg)
JFALL 2016
![Page 18: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/18.jpg)
LEAVE YOUR PHONE# IN EVERY SOURCE FILE
JUST-IN-TIME DOCUMENTATION
WRITE GREAT CODE, COMMENT IT
WRITE JUST ENOUGH DOCS, BUT NOT MORE
![Page 19: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/19.jpg)
CASES WHEN DOCUMENTATION AVOIDANCE FAILS
user manualapi guideonboarding guidecode commentsdesign docs...
![Page 20: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/20.jpg)
everywhere a user meets developmentYOU NEED DOCUMENTATION
![Page 21: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/21.jpg)
everywhere a user meets developmentYOU NEED DOCUMENTATION
a new team member is a userALSO,
![Page 22: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/22.jpg)
OPTIONS FOR WRITING
DOCUMENTATION
![Page 23: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/23.jpg)
CODE
good naminggood structurecommentsjavadocis documentation
up-to-date
![Page 24: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/24.jpg)
CODEas documentation fails when > 30k
good naminggood structurecommentsjavadocup-to-date
![Page 25: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/25.jpg)
JAVADOC
good for APIsuse overview.htmluse package.htmlno stupid javadocup-to-date
![Page 26: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/26.jpg)
*drivegoogle microsoft icloud sharepoint "f-share"
![Page 27: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/27.jpg)
WIKIsnobody got fired for buying atlassian
![Page 28: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/28.jpg)
WIKIs are where documentation goes to die – Joseph Wilk
![Page 29: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/29.jpg)
CODE and JAVADOC
mostly up-to-date
![Page 30: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/30.jpg)
CODE and
JAVADOC and DOCS
up-to-date?
![Page 31: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/31.jpg)
WHAT IF WE COULD USE DEV TOOLS FOR
DOCUMENTATION?
gitmavenjenkinsdocker
![Page 32: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/32.jpg)
1. docs → git 2. docs → build tools 3. docs → deployment tools
![Page 33: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/33.jpg)
GIT ❤ TEXT FILES
![Page 34: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/34.jpg)
![Page 35: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/35.jpg)
PLAIN TEXT OPTIONSmarkdown
docbook
asciidoctorDITAA HTML
![Page 36: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/36.jpg)
PLAIN TEXT OPTIONSmarkdown
docbook
asciidoctorDITAA HTML##
#
![Page 37: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/37.jpg)
MARKDOWN+ light weight + easy to write + easy to read - limited
AFirstLevelHeader====================
ASecondLevelHeader---------------------
Nowisthetimeforallgoodmentocometotheaidoftheircountry.Thisisjustaregularparagraph.
Thequickbrownfoxjumpedoverthelazydog'sback.
###Header3
>Thisisablockquote.>>Thisisthesecondparagraphintheblockquote.>>##ThisisanH2inablockquote
![Page 38: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/38.jpg)
FIRST THERE WAS MARKDOWNMarkdown (John Gruber)
http://daringfireball.net/projects/markdown
![Page 39: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/39.jpg)
THEN THERE WAS MARKDOWNMarkdown Github Flavored Markdown Extra MultiMarkdown
(John Gruber)
![Page 40: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/40.jpg)
THEN THERE WAS MARKDOWNMarkdown Github Flavored Markdown Extra MultiMarkdown CommonMark https://xkcd.com/927/
![Page 41: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/41.jpg)
ASCIIDOCTOR+ medium weight + easy to write + easy to read + comprehensive + maven support + 1 version
#AFirstLevelHeader
##ASecondLevelHeader
Nowisthetimeforallgoodmentocometotheaidoftheircountry.Thisisjustaregularparagraph.
Thequickbrownfoxjumpedoverthelazydog'sback.
###Header3
>Thisisablockquote.>>Thisisthesecondparagraphintheblockquote.>>##ThisisanH2inablockquote
![Page 42: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/42.jpg)
ASCIIDOCTOR+ Table of contents + Output to epub, pdf, html, docbook + Bibliography + Footnotes + Macros+ Substitutions
![Page 43: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/43.jpg)
ASCIIDOCTOR+ file inclusions:
[source,java]----include::org/asciidoctor/Asciidoctor.java[lines=5..10]----
![Page 44: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/44.jpg)
ASCIIDOCTOR+ code callouts
[source,xml]----include::pom.xml----<1>AddsArquillianCube<2>Fromthepointofview
![Page 45: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/45.jpg)
PLAIN TEXT CHOICES
markdown asciidoctorREADME:1 EVERYTHING ELSE:
1 github does support README.adoc using asciidoctor format
![Page 46: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/46.jpg)
1. docs → git 2. docs → build tools 3. docs → deployment tools
![Page 47: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/47.jpg)
maven
maven+
guide.html
guide.pdf
=
![Page 48: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/48.jpg)
1. docs → git 2. docs → build tools 3. docs → deployment tools
![Page 49: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/49.jpg)
guide.pdf +guide.html
=+ maven
mavendockerhttpd
profit
![Page 50: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/50.jpg)
result
![Page 51: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/51.jpg)
WHAT IF WE COULD USE DEV TOOLS FOR A
USER MANUAL?
![Page 52: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/52.jpg)
text and screenshotsUSER MANUAL:
![Page 53: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/53.jpg)
text and screenshotsUSER MANUAL:
![Page 54: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/54.jpg)
screenshots considered harmful
![Page 55: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/55.jpg)
I have made this longer than usual because I have not had time to make it shorter.
![Page 56: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/56.jpg)
I have made this longer than usual because I have not had time to make it shorter.
![Page 57: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/57.jpg)
screenshots are always out-of-date
Windows™ 10 Admin Guide
1. Logging inAn 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
![Page 58: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/58.jpg)
«intentionally left blank for dramatic purposes»
![Page 59: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/59.jpg)
UP-TO-DATE USER MANUAL
CASE STUDY
![Page 60: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/60.jpg)
Identity & access management - 2FA for critical infrastructure - Localized authorization - 4 eyes principle - Installs as software appliance - Web App - Native mobile apps
![Page 61: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/61.jpg)
vaults for secure team shares4 eyes principle
![Page 62: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/62.jpg)
85 PAGES88 IMAGES
USER MANUAL
![Page 63: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/63.jpg)
the 85 pages are written in asciidoc, converted using asciidoctor(all text is written by a human)
![Page 64: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/64.jpg)
the 88 screenshots are captured during testing, achieving 90% code coverage
![Page 65: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/65.jpg)
100%automated
![Page 66: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/66.jpg)
arquillianmaven
mavenaShotgraphene
TOOLS USED FOR DOCUMENTATION
![Page 67: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/67.jpg)
arquillianmaven
mavenaShotgraphene
![Page 68: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/68.jpg)
a functional, integration and acceptance test platform
http://arquillian.org/
![Page 69: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/69.jpg)
modules
a functional, integration and acceptance test platform
http://arquillian.org/
deploymentcontainers packaging injection
![Page 70: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/70.jpg)
webdriver
http://arquillian.org/
integrationrecording
wildfly cube
tomcat
etcglassfish
![Page 71: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/71.jpg)
Captures screenshot on test failure with Arquillian Recorder
http://arquillian.org/recording
![Page 72: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/72.jpg)
Skips a testif the issue is not done.
Runs a testif the issue is done.
Closes a issue if the test is successful
http://arquillian.org/integration
@Test@Jira("ARQ-1907")publicvoidtest1(){}
@Test@Github("123")publicvoidtest2(){}
![Page 73: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/73.jpg)
@RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser;
@Test public void step1LogIn() { } }
Anatomy of a test case1
3
2
![Page 74: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/74.jpg)
@RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser;
@Test public void step1LogIn() { } }
Anatomy of a test case1
3
2
![Page 75: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/75.jpg)
@RunWith(Arquillian.class) public class LoginTest { @Drone private WebDriver browser;
@Test public void step1LogIn() { } }
Anatomy of a test case1
3
2
![Page 76: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/76.jpg)
@Test public void login() { browser .navigate() .to("https://test.com/login");
browser .findElement(By.name("username")) .sendKeys("bertjan");
Implement test case1
3
2
4
5
![Page 77: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/77.jpg)
@Test public void login() { browser .navigate() .to("https://test.com/login");
browser .findElement(By.name("username")) .sendKeys("bertjan");
Implement test case1
3
2
4
5
![Page 78: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/78.jpg)
browser .findElement(By.name("username")) .sendKeys("bertjan");
browser .findElement(By.name("password")) .sendKeys("schrijver");
Implement test case1
3
2
4
5
![Page 79: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/79.jpg)
browser .findElement(By.name("password")) .sendKeys("schrijver");
browser .findElement(By.id("login")) .click();
Implement test case1
3
2
4
5
![Page 80: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/80.jpg)
browser .findElement(By.id("login")) .click();
Assert.assertEquals("home", browser .findElement(By.tagName("title")) .text()); }
Implement test case1
3
2
4
5
![Page 81: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/81.jpg)
arquillianmaven
mavenaShotgraphene
![Page 82: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/82.jpg)
a wrapper for Selenium/WebDriver
graphenehttp://arquillian.org/arquillian-graphene/
![Page 83: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/83.jpg)
Page Objects encapsulate requests and HTML
https://martinfowler.com/bliki/PageObject.html
![Page 84: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/84.jpg)
browser .navigate() .to("https://test.com/login");
Using Page Objects
![Page 85: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/85.jpg)
browser .navigate() .to("https://test.com/login");
Using Page Objects
LoginPage loginPage = Graphene.goTo(LoginPage.class);
![Page 86: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/86.jpg)
browser .findElement(By.name("username")) .sendKeys("bertjan"); browser .findElement(By.name("password")) .sendKeys("schrijver"); browser.findElement(By.id("login")).click();
Using Page Objects
![Page 87: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/87.jpg)
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
![Page 88: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/88.jpg)
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
![Page 89: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/89.jpg)
arquillianmaven
mavenaShotgraphene
![Page 90: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/90.jpg)
WebDriver Screenshot utility. Take screenshots, crop, prettify, compare.
aShothttps://github.com/yandex-qatools/ashot
![Page 91: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/91.jpg)
take full screenshots
\
aShothttps://github.com/yandex-qatools/ashot
![Page 92: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/92.jpg)
Screenshot screenshot = new AShot().takeScreenshot(browser);
Path targetFile = Paths.get( "target/screenshots", name + ".png");
ImageIO.write( screenshot.getImage(), "png", targetFile.toFile());
Take a Screenshot1
3
2
![Page 93: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/93.jpg)
Screenshot screenshot = new AShot().takeScreenshot(browser);
Path targetFile = Paths.get( "target/screenshots", name + ".png");
ImageIO.write( screenshot.getImage(), "png", targetFile.toFile());
Take a Screenshot1
3
2
![Page 94: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/94.jpg)
Screenshot screenshot = new AShot().takeScreenshot(browser);
Path targetFile = Paths.get( "target/screenshots", name + ".png");
ImageIO.write( screenshot.getImage(), "png", targetFile.toFile());
Take a Screenshot1
3
2
![Page 95: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/95.jpg)
compose partials
aShothttps://github.com/yandex-qatools/ashot
![Page 96: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/96.jpg)
Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username")));
Screenshot Composition1
3
2
![Page 97: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/97.jpg)
Screenshot screenshot = new AShot() .takeScreenshot(browser, browser.findElement( By.id("username")));
Screenshot Composition1
3
2
requires JQuery in target page
![Page 98: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/98.jpg)
Screenshot screenshot = new AShot() .imageCropper(new IndentCropper(50)) .takeScreenshot(browser, browser.findElement( By.id("username")));
Screenshot Composition1
3
2
![Page 99: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/99.jpg)
new AShot().takeScreenshot(browser, browser.findElements( ByJQuery.selector( "input[name='username'], a:contains('Sign in')")));
Screenshot Composition1
3
2
![Page 100: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/100.jpg)
new AShot().takeScreenshot(browser, browser.findElements( ByJQuery.selector( "input[name='username'], a:contains('Sign in')")));
Screenshot Composition1
3
2
PLURAL!
![Page 101: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/101.jpg)
arquillianmaven
mavenaShotgraphene
![Page 102: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/102.jpg)
keyhub-backend
Maven module dependencieswar
![Page 103: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/103.jpg)
keyhub-tests
keyhub-backend
Maven module dependencieswar
![Page 104: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/104.jpg)
keyhub-tests
keyhub-backend
keyhub-manual
Maven module dependencies
war
war
![Page 105: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/105.jpg)
keyhub-tests
keyhub-backend
keyhub-manual
keyhub-app
Maven module dependencies
war
war
![Page 106: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/106.jpg)
graphene aShotarquillian++ =
screenshots
Maven module: keyhub-tests
![Page 107: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/107.jpg)
maven
maven+ =
screenshots
maven test module
![Page 108: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/108.jpg)
+ maven
maven+
manual.html
manual.pdf
=manual.adoc
maven manual module
![Page 109: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/109.jpg)
+ maven
mavenmanual.war=
manual.html
manual.pdf
maven manual module
![Page 110: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/110.jpg)
application.war +manual.war
=+ maven
mavendockerwildfy
profit
maven app module
![Page 111: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/111.jpg)
THE RESULT
ANUP-TO-DATEUSER MANUAL
![Page 112: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/112.jpg)
THE RESULT
![Page 113: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/113.jpg)
THE RESULT
![Page 114: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/114.jpg)
THE RESULT 90%
TEST COVERAGE
![Page 115: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/115.jpg)
AUTOMATE
ALL THE THINGS!
![Page 116: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/116.jpg)
$
![Page 117: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/117.jpg)
$%
![Page 118: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/118.jpg)
$%
&
![Page 119: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/119.jpg)
SOLUTIONS FOR WHEN DOCUMENTATION
AVOIDANCEFAILS
![Page 120: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/120.jpg)
1. use plain text2. keep code and docs together3. integrate docs into your dev process4. automate all the things
![Page 121: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/121.jpg)
writethedocs.orgasciidoctor.orgarquillian.orgmaven.apache.org
sources
![Page 122: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/122.jpg)
THANK YOU!
@dashorst
![Page 123: Solutions for when documentation fails](https://reader035.vdocuments.us/reader035/viewer/2022062523/5a64d6207f8b9a4d0b8b4a89/html5/thumbnails/123.jpg)
QUESTIONS?
@dashorst