Upload
annice-ellis
View
214
Download
0
Tags:
Embed Size (px)
Citation preview
Copyright Edmunds Inc. (the “Company”). All rights reserved.Edmunds®, Edmunds.com®, the Edmunds.com car design, Inside Linesm , CarSpacesm and AutoObserver® are proprietary trademarks of the Company. This document contains proprietary and/or confidential information of the Company. No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Company, and any such disclosure requires the express approval of the Company.
7 Rules for Creating World Class Technical Documentation
SCALE Edition
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Agendao Introduction
o What you’ll be able to do at the end of thiso Who are you?o Who am I?o Why am I here?
o Getting Down to Businesso Defining World Class Technical Documentationo The 7 Ruleso Real World Examples
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
What you’ll be able to do at the end of thiso When this is over, you will be able to create technical
documentation that is:o easier to understando more engagingo becomes more accurate over timeo clearer in purpose
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
The Golden Rule of Technical Writingo The Reader is lending you his or her mind. Don’t
abuse it. Don’t confuse it!
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Who are you?o Profile
o I am hands on technology persono I read and view a good deal of technical documentationo I write technical documentation
o Experienceo I find most technical documentation so exciting that I have trouble
sleeping afterwards.o I find most technical documentation so boring I have absolutely no
problem sleeping afterwards.o Ability
o Creating a technical document is absolutely no problem for me.o I’d rather have three teeth extracted than create a tech doc.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Who Am I?
You are not your things.
Yes, you are!
We all wear black gloves. It’s a gang
thing.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Who am I?
Shameless self-promotion
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Getting Down to Business
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Define World ClassTechnical Documentation
o Accurateo Engagingo Purposefulo Easy to understand
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
The 7 Rules1. Dry sucks2. Embrace revision3. Before you start, be clear about what you want your
reader to do after you end4. Write to an outline, always5. clarity = illustrations + words6. Watch the pronouns7. When dealing with abstraction… examples,
examples, examples
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
1. Dry suckso The currency of the future is human attentiono “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
o You need to get and keep the reader’s attentiono You have a lot of competition
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
1. Dry Suckso Take riskso Getting attention is always risky
o Risk α clarityo The clearer you are the more risks you can take
I am the Presentation Tier. I display information.
I am the coolest guy around!
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.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
1. Dry suckso !(Dry) = youo Figure out what gets your attention in a good
technical doc and then do ito Here’s mine:
o Humoro Simple languageo Pertinent analogieso Real world examples
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
1. Dry suckso 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.
.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
1. Dry Suckso If it ain’t fun for you, it ain’t fun for themo Analogies unsucko Beware the drone of redundancy
o Bad dog: Use the jack to jack up your caro Good dog: Use the jack to elevate you car
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
2. Embrace revisiono It’s not a question of accurate.o 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
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
2. Embrace revision
Figure 1: The documentation development iteration cycle is surprisingly similar to the software development iteration cycle.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
2. Embrace revision
o As technology releases increase, revision cycles must become shorter
o Print = 6 months o Web = today DateTime.Now
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
3. Before you start, be clear about what you want your read to do after you endo Technical documentation is about subsequent
behavioro There is always an expected result
o You will be able to make a batch of cookies.o You will be able to do a heart transplant.
o Be clear: state at the beginning what the reader will be able to do at the end
o Keep mystery in the mystery novels
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
3. Before you start, be clear about what you want your read to do after you endo Technical documentation is about subsequent
behavioro There is always an expected result
o You will be able to make a batch of cookies.o You will be able to do a heart transplant.
o Be clear: state at the beginning what the reader will be able to do at the end
o Keep mystery in the mystery novels
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
3. Before you start, be clear about what you want your read to do after you endo Plan your reinforcementso The minimum is 3 reps
o Tell ‘em what you going to tell ‘emo Tell ‘emo Tell ‘em what you told them
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
4. Write to an outline, always
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
4. Write to an outline, always
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
4. Write to an outline, always
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
4. Write to an outline, alwayso Use the basic rules of outliningo In case you were sleeping in 8th Grade:
o You must have at least 2 sub levels to a level.o You must have at least 2 sentences in every level.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
4. Write to an outline, always
Bad Dog!
o Assumed Knowledgeo How to write Java codeo How to use Maven at the command
lineo Know how to write Web Appso Know about the file system of a web
app• WEB-INF should have meaning
o Know how to run Jettyo Know MVC
• “Controller” has meaning• “View” has meaning
Good Dog!
o Assumed Knowledgeo How to write Java codeo How to use Maven at the
command lineo Know how to write Web Apps
• Know about the file system of a web app
• WEB-INF should have meaningo Know how to run Jettyo Know MVC
• “Controller” has meaning• “View” has meaning
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
5. clarity = illustrations + words
Is this man in agony or ecstasy?
Illustrations describe the instance.Words describe the abstraction.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
5. clarity = illustrations + words
Figure 1: Enrico Fabris celebrating his first gold at the 2006 Winter Olympics in
Torino.
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
5. clarity = illustrations + words
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
5. clarity = illustrations + words
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
5. clarity = illustrations + words
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
5. clarity = illustrations + wordso The reader’s attention is usually drawn to the illustration firsto Write around the illustrationo 1 Concept = 1 Illustrationo Number caption
o Figureso Tableso Listing
o Always value add to figure captiono Reference your captions in the copy
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
5. Clarity = illustrations + words
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
6. Watch the pronouns
itthis
that
they
these those
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
6. Watch the pronounso The culprits
o ito thiso thato theyo theseo those
o What is the reference?
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
6. Watch the pronouns
o Trafalgabors are a fundamental component of the Weebietatas framework. This screencast shows you what they are about and how to use them.
o Trafalgabors are a fundamental component of the Weebietatas framework. This screencast shows you what Trafalgabors are about and how to use them.
Trafalgabors Weebietatas
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
6. Watch the pronounso 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?
o 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?
Powerpoint slideshow mode
click sound
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
7. When dealing with abstraction… examples, examples, exampleso Abstraction is hard to geto Support a pattern of presentation
o Expositiono Diagramo Example
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
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.
if 7 = 3 + 4 and 3 + 4 = 5 + 2 then 7 = 5 + 2
Example:
Figure 1: The Transitive Property of Equality is a fundamental principle of elementary algebra
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
7. When dealing with abstraction… examples, examples, exampleso 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 <img src="file:///c:/projects/6Rules/images/factoryPattern.jpg" border="0" /> */public class CheeseFactoryImpl implements FoodStoreFactory {...
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Real World Exampleso From the trenches
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Real World Examples
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Real World Example
Figure 1: Asynchronous JavaScript uses the callback function pattern
1. Browser invokes JavaScript call function
2. Call function makes http request
3. Web server process Ajax request and created http response
4. Ajax callback function renders data from web sever to div element on browser page
Information retrieval using Ajax is a 4 step process. (Please see Figure 1).
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Real World Example
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
The 7 Rules
1. Dry sucks2. Embrace revision3. Before you start, be clear about what you want your
reader to do after you end4. Write to an outline, always5. clarity = illustrations + words6. Watch the pronouns7. When dealing with abstraction… examples,
examples, examples
No part of this document or the information it contains may be used, or disclosed to any person or entity, for any purpose other than advancing the best interests of the Edmunds Inc., and any such disclosure requires the express approval of Edmunds Inc.
Above all else, do not confuse