Better Documentation
-
Upload
sathya-srinivasan -
Category
Technology
-
view
1.640 -
download
0
description
Transcript of Better Documentation
Better Documentation
…simple steps for greater impact!
Sathya SrinivasanTechnical ArchitectContent & Portal Solutions
“The value of documentation is only to be realized if the document is well done. If it is poorly done, it will be worse
than no document at all.”Gerald M Weinberg
“In the beginner’s mind there are many possibilities. In the expert’s mind, there are few”Shunryu Suzuki
Agenda
Core principles
Before-After
Best practices
Perspective matters
Fat content?Calories?Sugar! I
want it!
mmm… cookie…
Identify your readers
What do they need?
What do they need?
How much will they understand?
Know your readers
Specify your target audience
Provide context (background information)
Specify scope
Do not assume reader’s background beyond minimum
Provide future references
It’s taken all my life to learn what not to play.Dizzy Gillespie
Expand on content
Level 0 : Summary
Level 1 : High-level
Level 2 : Detail
Reference
Abstract or Summary
For the casual reader or the executive
Provides enough information to understand the purpose and what the document achieves
High-level detail
For the more involved reader or the manager
Provides enough data points to conduct meetings or conversations
Full Detail
For the involved reader Provides in-depth
explanation of the high-level topics
Reference
Give something for those interested in following up
Related material
Documentation supporting claims made in text
Add level of detail
Level 0 Level 1 Level 2
How to make your points stick?
Simplicity
Unexpectedness
Concreteness
Credibility
Emotion
Story
“Our mission is to become the international leader in the space industry through maximum team-centered innovation and strategically targeted aerospace initiatives.”
“…put a man on the moon and return him safely by the end of the decade.”
6 ways to see and 6 ways to show
Use the right picture to convey your data
Use fonts and type to emphasize your point
Contrast
Repetition
Alignment
Proximity
Size
WeightStructure
Form
Direct ion
color
Constraints lead to creativity
Agenda
Core principles
Before-After
Best practices
Simplicity means the achievement of maximum effect with minimum means.Dr. Koichi Kawana
Darth Vader…
Yoda?
…or…
Microsoft…
Apple?
…or…
How to create captivating graphics
How to create captivating graphics
How to create a good-looking front page
alignment
contrast
proximityrepetition
How to strengthen your resume
Your message is important – don’t drown it
Pick the right graphic to express your data
Best Practices
Core principles
Before-After
Best practices
Common Best Practices Provide visual equivalents where applicable
DO NOT USE ALL-CAPS – It reduces readability
Use Only Initial Caps When Necessary – It’s distracting
Keep consistent fonts
CAN YOU READ THIS BIG BLOB OF TEXT SCREAMING AT YOU BUT NEVERTHELESS CONTAINS VERY IMPORTANT INFORMATION?
Or can you read this equally big blob of text that contains equally important information without screaming?
And how about this very important
piece of information contained in
this big blob of text with appropriate
emphasis and white space?
Important Information About Big Company But With All Initial Caps…
…or important information about Big Company with initial caps for nouns only?
Best Practices : Document
Do not separate content from heading
Make your documents printer-friendly
Apply the corporate template to the document even if it is internal or one-off
and…
Correct document properties
Include your name and company name
… not your someone else’s!
Correct your reds, greens, and blues
Red – Spelling errors
Green – Grammatical errors
Blue – Contextual errors (new in 2007)
Do not leave empty rows in tables
You can always hit the TAB button later!
Use format and styling
Identify headings and normal text
Use them for generating TOC
Best Practices : Presentation Pictures + Text = Better presentation
Use animation only when needed (such as adding suspense)
Presentation = Slides [+ Notes + Handout]
Reduce the footprint of the document
Remove empty bullets
and…
Apply corporate theme
… even if it is a one-off deck
Apply slide style on copy/paste
Best Practices : Spreadsheet
Avoid using macros when possible
Remove unwanted sheets (Sheet2, Sheet3)
Rename sheets to reflect the associated content
and…
Distinguish the header
Wrap text in cells
Make spreadsheets printer-friendly
Repeat headers Set orientation Adjust page breaks Add cell borders Add header/footer info
Adjust your columns
Best Practices : E-mail
Use Spelling & Grammar check before hitting ‘send’
Read what you wrote at least once
Add your contact information – always!
Do not cut and paste images – insert them as JPEG attachments
“First you master your instrument. Then you master the music. Then you forget about all the shit you just learned and just play”Charlie Parker
Don’t have the time?
References
Hyperlinks
http://www.garrreynolds.com http://www.presentationzen.com http://www.beyondbulletpoints.com
http://www.istockphoto.com http://www.dreamstime.com