7 Rules for Creating World Class Technical Documentation

1. 7 Rules for Creating World Class Technical Documentation SCALEEdition

2. Agenda • Introduction • What you’ll be able to do at the end of this • Who are you? • Who am I? • Why am I here? • Getting Down to Business • Defining World Class Technical Documentation • The 7 Rules • Real World Examples

3. What you’ll be able to do at the end of this • When this is over, you will be able to create technical documentation that is: • easier to understand • more engaging • becomes more accurate over time • clearer in purpose

4. The Golden Rule of Technical Writing • The Reader is lending you his or her mind. Don’t abuse it. Don’t confuse it!

5. Who are you? • Profile • I am hands on technology person • I read and view a good deal of technical documentation • I write technical documentation • Experience • I find most technical documentation so exciting that I have trouble sleeping afterwards. • I find most technical documentation so boring I have absolutely no problem sleeping afterwards. • Ability • Creating a technical document is absolutely no problem for me. • I’d rather have three teeth extracted than create a tech doc.

6. Who Am I? Yes, you are! You are not your things. We all wear black gloves. It’s a gang thing.

7. Who am I? Shameless self-promotion

8. Getting Down to Business

9. Define World ClassTechnical Documentation • Accurate • Engaging • Purposeful • Easy to understand

10. The 7 Rules • Dry sucks • Embrace revision • Before you start, be clear about what you want your reader to do after you end • Write to an outline, always • clarity = illustrations + words • Watch the pronouns • When dealing with abstraction… examples, examples, examples

11. 1. Dry sucks • The currency of the future is human attention • “Attention economics is an approach to the management of information that treats human attention as a scarce commodity, and applies economic theory to solve various information management problems.” – wikipedia • You need to get and keep the reader’s attention • You have a lot of competition

12. I am the Presentation Tier. I display information. I am the coolest guy around! Dry Sucks • Take risks • Getting attention is always risky • Risk α clarity • The clearer you are the more risks you can take I am the Business Tier. I transform data into information. I am the smartest guy around! I am the Data Tier. I provide data. I get no respect. Figure 1: 3-tier architecture is a basic pattern for achieving separation of concerns.

13. Dry sucks • !(Dry) = you • Figure out what gets your attention in a good technical doc and then do it • Here’s mine: • Humor • Simple language • Pertinent analogies • Real world examples

14. 1. Dry sucks • Use the second person The way to enhance the charge distribution is by adjusting the degree of resistance in the memory array. You enhance the charge distribution by adjusting the degree of resistance in the memory array. .

15. Dry Sucks • If it ain’t fun for you, it ain’t fun for them • Analogies unsuck • Beware the droneof redundancy • Bad dog: Use the jack to jack up your car • Good dog: Use the jack to elevate you car

16. 2. Embrace revision • It’s not a question of accurate. • It’s a question of how accurate. "The number of bugs in technical documentation for Microsoft communication protocols continues to grow, according to court documents filed for ongoing antitrust oversight of the company in the US. Problems with the technical documentation — which includes 1,660 identified bugs as of Dec. 31, up from 1,196 bugs on Nov. 30 — remain the major complaint from lawyers representing the group of 19 states that joined the US Department of Justice's antitrust lawsuit against Microsoft. Lawyers for the states have complained repeatedly that technical documentation issues are opening faster than Microsoft can close them. Nearly 800 Microsoft employees are working on the more than 20,000 pages of technical documentation, according to the court documents filed Wednesday.” -- Slashdot 1/23/2009

17. 2. Embracerevision Figure 1: The documentation development iteration cycle is surprisingly similar to the software development iteration cycle.

18. 2. Embrace revision • As technology releases increase, revision cycles must become shorter • Print = 6 months   • Web = today  DateTime.Now

19. 3. Before you start, be clear about what you want your read to do after you end • Technical documentation is about subsequent behavior • There is always an expected result • You will be able to make a batch of cookies. • You will be able to do a heart transplant. • Be clear: state at the beginning what the reader will be able to do at the end • Keep mystery in the mystery novels

20. 3. Before you start, be clear about what you want your read to do after you end • Technical documentation is about subsequent behavior • There is always an expected result • You will be able to make a batch of cookies. • You will be able to do a heart transplant. • Be clear: state at the beginning what the reader will be able to do at the end • Keep mystery in the mystery novels

22. 3. Before you start, be clear about what you want your read to do after you end • Plan your reinforcements • The minimum is 3 reps • Tell ‘em what you going to tell ‘em • Tell ‘em • Tell ‘em what you told them

23. 4. Write to an outline, always

24. 4. Write to an outline, always

25. 4. Write to an outline, always

26. 4. Write to an outline, always • Use the basic rules of outlining • In case you were sleeping in 8th Grade: • You must have at least 2 sub levels to a level. • You must have at least 2 sentences in every level.

27. 4. Write to an outline, always Bad Dog! Good Dog! Assumed Knowledge How to write Java code How to use Maven at the command line Know how to write Web Apps Know about the file system of a web app WEB-INF should have meaning Know how to run Jetty Know MVC “Controller” has meaning “View” has meaning • Assumed Knowledge • How to write Java code • How to use Maven at the command line • Know how to write Web Apps • Know about the file system of a web app • WEB-INF should have meaning • Know how to run Jetty • Know MVC • “Controller” has meaning • “View” has meaning

28. 5. clarity = illustrations + words • Illustrations describe the instance. • Words describe the abstraction. Is this man in agony or ecstasy?

29. 5. clarity = illustrations + words Figure 1: EnricoFabris celebrating his first gold at the 2006 Winter Olympics in Torino.

30. 5. clarity = illustrations + words

31. 5. clarity = illustrations + words

32. 5. clarity = illustrations + words

33. 5. clarity = illustrations + words • The reader’s attention is usually drawn to the illustration first • Write around the illustration • 1 Concept = 1 Illustration • Number caption • Figures • Tables • Listing • Always value add to figure caption • Reference your captions in the copy

34. 5. Clarity = illustrations + words

35. 6. Watch the pronouns they it this that those these

36. 6. Watch the pronouns • The culprits • it • this • that • they • these • those • What is the reference?

37. 6. Watch the pronouns • Trafalgabors are a fundamental component of the Weebietatas framework. This screencast shows you what they are about and how to use them. • Trafalgabors are a fundamental component of the Weebietatas framework. This screencast shows you what Trafalgabors are about and how to use them. Trafalgabors Weebietatas

38. 6. Watch the pronouns • I am doing a presentation in Powerpoint 2007 Win. In slideshow mode, every time I move between slides hitting the space bar I get an awful click sound. Does anybody know how to make that go away? • I am doing a presentation in Powerpoint 2007 Win. In slideshow mode, every time I move between slides hitting the space bar I get an awful click sound. Does anybody know how to make that sound go away? click sound Powerpoint slideshow mode

39. 7. When dealing with abstraction… examples, examples, examples • Abstraction is hard to get • Support a pattern of presentation • Exposition • Diagram • Example

40. 7. When dealing with abstraction… examples, example, examples The Transitive Property of Equality is defined as follows: If a = b and b = c, then a = c. Figure 1: The Transitive Property of Equality is a fundamental principle of elementary algebra Example: if 7 = 3 + 4 and 3 + 4 = 5 + 2 then 7 = 5 + 2

41. 7. When dealing with abstraction… examples, examples, examples • Goes for commenting too! /** * @author Bob Reselman * */ package com.edmunds.training.foodstore.service; import com.edmunds.training.foodstore.api.FoodStoreFactory; import com.edmunds.training.foodstore.api.Food; /** * A factory object that implements the FoodStoreFactory interface. This factory produces objects * that derive from the AbstractCheeseImpl object. * * @see AbstractCheeseImpl * @see <a href="http://en.wikipedia.org/wiki/Factory_method_pattern">Factory Method Design Pattern in Wikiepedia</a> * @see <imgsrc="file:///c:/projects/6Rules/images/factoryPattern.jpg" border="0" /> */ public class CheeseFactoryImpl implements FoodStoreFactory { . . .

42. From the trenches Real World Examples

43. Real World Examples

44. Real World Example Information retrieval using Ajax is a 4 step process. (Please see Figure 1). Browser invokes JavaScript call function Call function makes http request Web server process Ajax request and created http response Ajax callback function renders data from web sever to div element on browser page Figure 1: Asynchronous JavaScript uses the callback function pattern

45. Real World Example

46. The 7 Rules • Dry sucks • Embrace revision • Before you start, be clear about what you want your reader to do after you end • Write to an outline, always • clarity = illustrations + words • Watch the pronouns • When dealing with abstraction… examples, examples, examples

47. Above all else, do not confuse