The document provides advice for writing documentation based on Hemingway's writing style. It recommends focusing documentation on intermediate users trying to become experts, and accounting for different learning styles like visual and kinesthetic. Key advice includes being minimalist with words, using present tense, preferring shorter words, being direct, making information stick through formatting and diagrams, writing for everyone by avoiding cultural references, and testing documentation through peer review.
Post Quantum Cryptography – The Impact on Identity
If Hemingway Wrote JavaDocs
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
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?
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
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
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.”
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.
Hemingway was famous for his writing style, which was powerfully descriptive while being economical with the language.
Examples of wide-reaching references: Cooking, football (even though it means different things in different countries), other sports.
Example of a possibly offensive reference: Beer. Many cultures have beer, but many others do not consume alcohol. Try bread. Almost every culture has some form of bread.
Using present tense applies to making things easier to understand, too.
Formal writing, including all technical writing, does not use contractions. Also, they can be more readily misunderstood.
Humor is always culturally bound and often does not travel well into other cultures.
Use the same word for the same idea in all cases. Trying to vary the terminology can cause confusion.
It may seem boring to never vary your terminology or your sentence structure and to avoid all humor, but think of the audience. Their goal is to learn what they need to know as quickly as possible. Consistency in terminology and sentence structure and even document structure (the arrangement of heading) helps readers find what they need and learn it quickly.