Copyright Edmunds Inc. (the “Company”). All rights reserved. Edmunds ®, Edmunds.com ®, the...

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


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


The Golden Rule of Technical Writingo The Reader is lending you his or her mind. Don’t

abuse it. Don’t confuse it!


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.


Who Am I?

You are not your things.

Yes, you are!

We all wear black gloves. It’s a gang

thing.


Who am I?

Shameless self-promotion


Getting Down to Business


Define World ClassTechnical Documentation

o Accurateo Engagingo Purposefulo Easy to understand


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


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


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.


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


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.

.


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


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


2. Embrace revision

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


2. Embrace revision

o As technology releases increase, revision cycles must become shorter

o Print = 6 months o Web = today DateTime.Now


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


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



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


4. Write to an outline, always






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.



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


5. clarity = illustrations + words

Is this man in agony or ecstasy?

Illustrations describe the instance.Words describe the abstraction.



Figure 1: Enrico Fabris celebrating his first gold at the 2006 Winter Olympics in

Torino.








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


5. Clarity = illustrations + words


6. Watch the pronouns

itthis

that

they

these those


6. Watch the pronounso The culprits

o ito thiso thato theyo theseo those

o What is the reference?


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


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


7. When dealing with abstraction… examples, examples, exampleso Abstraction is hard to geto Support a pattern of presentation

o Expositiono Diagramo Example


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


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


Real World Exampleso From the trenches


Real World Examples


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


Real World Example


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


Above all else, do not confuse

Date post:	18-Dec-2015
Category:	Documents
Upload:	annice-ellis
View:	213 times
Download:	0 times

Copyright Edmunds Inc. (the “Company”). All rights reserved. Edmunds ®, Edmunds.com ®, the...

Documents