1. If Hemingway Wrote Javadoc
September 2–3, 2020
springone.io
Jay Bryant – Spring Technical Writer – @jbryant
Josh Cummings – Spring Security Maintainer – @jzheaux

2. Safe Harbor Statement
ThefollowingisintendedtooutlinethegeneraldirectionofVMware'sofferings.Itisintendedforinformationpurposesonlyandmay notbeincorporated
intoanycontract. Anyinformationregardingpre-releaseofVMwareofferings,futureupdatesorotherplannedmodificationsis subjecttoongoing
evaluationbyVMwareandissubjecttochange.Thisinformationisprovidedwithoutwarrantyoranykind, expressorimplied, and isnotacommitmentto
deliveranymaterial,code,orfunctionality,and shouldnotberelieduponin makingpurchasingdecisionsregardingVMware's offerings.Thesepurchasing
decisionsshould onlybebasedon featurescurrentlyavailable. Thedevelopment,release,and timingofanyfeaturesorfunctionalitydescribedfor
VMware'sofferingsin thispresentationremainatthesolediscretionofPivotal. Pivotalhasnoobligationtoupdateforwardlookinginformationin this
presentation.
2
If you are a VMware employee and your
talk contains forward facing information,
please include this slide at the beginning or
conclusion of the presentation.
Remove this text box before presenting.

3. /**
* Blackhats were <i>furious</i> when they saw us
* using <a href=“https://doc.example.org”>
* this best practice</a>.
**/
public void grantPermission(String permission) {
/**
* My CTO doubled my salary after
* <a href=“https://doc.example.org”>this simple
* trick</a> saved the company millions.
**/
public Risk computeRisk(Factors factors) {
Idea #1 - Clickbait

4. I think you should just #RTFM!
11:32 AM · 28 Feb 2020
22 43 people are Tweeting about this
Disgruntled Documenter
@iamdisgruntled
Idea #2 - Chastisement

5. Idea #3 – Reverse Psychology
You’re the 1-millionth visitor to our documentation.
You were evaluated as the winner of today’s 1-millionth visitor a few minutes ago by our
system. As your reward, you may choose one exclusive part of our documentation to visit!
Which will it be?
CHOOSE DOCS CHOOSE DOCS CHOOSE DOCS

6. 1. Know Your Audience
2. Be Minimal and Direct
3. Make It Stick
4. Write For Everyone
5. Test

7. Know Your
Audience

8. Skill Level
Users
Beginners Intermediates Experts
How Skilled Are Your
Users?

9. Focus on your Intermediates
AND
Your Beginners trying to become
Intermediates

10. Based on data published at https://vark-learn.com/introduction-to-vark/research-statist
Visual Audio
Reading Kinesthetics
30%
22%
24% 24%
How Do
Your
Users
Learn?

11. Many engineers learn in a way
other than Reading

12. /**
* Get the entity id
*
* @return the entity id
*/
public String getEntityId() {
return this.entityId;
}
/**
* Set the entity id
*
* @param entityId the entity id
*/
public void setEntityId(String entityId)
{
this.entityId = entityId;
}

13. /**
* Get the relying party’s
* <a href="https://wiki.shibboleth.net/CONCEPT/EntityNaming">EntityID</a>.
*
* <p>
* Equivalent to the value found in the relying party's
* {@code <EntityDescriptor EntityID="..."/>}.
*
* <p>
* This value may contain several placeholders, which should be
* {@link DefaultRelyingPartyRegistrationResolver resolved}
* before use. They are {@code baseUrl}, {@code registrationId},
* {@code baseScheme}, {@code baseHost}, and {@code basePort}.
*
* @see DefaultRelyingPartyRegistrationResolver
* @return the relying party’s EntityID
*/
1
2
3
1 Beginner -> Intermediate: Show a link for terminology that a beginner might not understand
2 Intermediate: Explain a more advanced feature, including a link regarding its usage
3 VARK: Using paragraphs and markup to highlight important details

14. What was it like
when I didn’t
know this?
Am I writing to be
heard or to help?
Harder
Questions

15. Be a Minimalist

16. Use no more words than necessary
Before: “The fact that Java is used to implement the web service is an
implementation detail -- an important detail, but a detail nonetheless.”
(Source: Spring Web Service Reference Guide)
1
6
After: “Using Java to implement the web service is an implementation detail.”

17. Use Present Tense
Before: “In this tutorial, we will define a Web service that is created by a Human
Resources department.”
(Source: Spring Web Service Reference Guide)
1
7
After: “In this tutorial, we define a Web service that is created by a Human
Resources department.”
Called Simple Present or the Indefinite Present

18. Prefer Shorter Words
1
8
”utilize” => “use”
“allows you to” => “lets you”
“Don't use a five-dollar word when a fifty-cent word will do.” - Mark Twain

19. Be Direct

20. How to Be Direct
Avoid passive voice.
2
0
Talk directly to the audience. Use second person: “you”.
Before: “Note that, in Spring-WS, writing the WSDL by hand is not required”.
After: “Note that, in Spring-WS, you need not write the WSDL by hand.”

21. Make It Stick

22. Visu
al
Whitespac
e
Clean
1 of 6

23. Whitespac
e

24. Visu
al
Links
And remember to always use https://!
Credible
2 of 6

25. Links

26. Visu
al
Format
Clear
3 of 6

27. Format

28. Visu
al
Diagrams
Concrete
4 of 6

29. Diagrams

30. Kinestheti
cs
Use
Cases
Consistent
5 of 6

31. Use Cases

32. Kinestheti
cs
Usage
Complete
6 of 6

33. Usage

34. Another C to Remember
Correct

35. Write for Everyone

36. How to Write for Everyone (1)
3
6
Avoid cultural references.
If you must use them, choose wide-reaching references
Watch out for offensive references.

37. How to Write for Everyone (2)
3
7
Avoid Latin.
”e.g” => “for example”. “i.e” => “that is”.
Use present tense.

38. How to Write for Everyone (3)
3
8
Do not use contractions.
Avoid humor.
Use consistent terminology.

39. How to Write for Everyone (4)
3
9
Do not try to write literature.
Write to help.

40. Test

41. Use Tools
Read Aloud
Peer Review Rewrite

42. “The only kindof writingis
rewriting.”
- Ernest Hemingway

43. Be helpful

44. Stay Connected.
Be Helpful.
Spring Security Patterns, Day 2 @ 1:05 ET, Beginner Track
#springone@s1p