1 / 47

7 Rules for Creating World Class Technical Documentation

7 Rules for Creating World Class Technical Documentation. SCALE Edition. 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.

valora
Télécharger la présentation

7 Rules for Creating World Class Technical Documentation

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript


  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

  21. 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

  22. 4. Write to an outline, always

  23. 4. Write to an outline, always

  24. 4. Write to an outline, always

  25. 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.

  26. 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

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

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

  29. 5. clarity = illustrations + words

  30. 5. clarity = illustrations + words

  31. 5. clarity = illustrations + words

  32. 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

  33. 5. Clarity = illustrations + words

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

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

  36. 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

  37. 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

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

  39. 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

  40. 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 { . . .

  41. From the trenches Real World Examples

  42. Real World Examples

  43. 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

  44. Real World Example

  45. 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

  46. Above all else, do not confuse

More Related