If Hemingway Wrote JavaDocs
Download as PPTX, PDF3 likes477 views
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.
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
- 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
- 23. Whitespac e
- 24. Visu al Links And remember to always use https://! Credible 2 of 6
- 25. Links
- 27. Format
- 29. Diagrams
- 31. Use Cases
- 33. Usage
- 34. Another C to Remember Correct
- 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
Editor's Notes
- #2: Hemingway was famous for his writing style, which was powerfully descriptive while being economical with the language.
- #37: 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.
- #38: Using present tense applies to making things easier to understand, too.
- #39: 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.
- #40: 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.