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