<!--Docs are Cool-->

What is Documentation?

Is this documentation?

What about this?

Good documentation vs.
Evil documentation

make order out of chaos

clear

complete

concise

correct

comprehensible

audience-

specific

wrong

unclear

incomplete

interminable

inpenetrable

make chaos out of complexity

The cost of bad documentation...

--It is necessary for technical reasons that these warheads should be stored with the top at the bottom and the bottom at the top. In order that there may be no doubt as to which is the top and which is the bottom, for storage purposes it will be seen that the bottom of each head has been labeled with the word TOP.--

How many errors can you find?

---Watching TV all the time, its easy to see why their having trouble. TV interferes with them studying and it’s strong affect on children has alot to due with their grades. There’s other factors, too, including the indifference of parents like you and I. A Mom or Dad often doesn’t know grammer themselves. We should tell are children to study hard like we did at they’re age and to watch less TV then their classmates.---

Questions: Do the mistakes matter? Is there still meaning?

Is this content usable? Isn't this what editors are for?

Good People == Good Docs

Writers

Editors

Designers

Architects

Teachers

Coders

....YOU

Documentation - You Try It!

Toothbrushing

Step-by-Step

Try again!

Shoelace Installation

Come out and play with us!

fedoraproject.org/wiki/DocsProject

>

Introductions

Start off – what is documentation? (examples... how to do it, how we did it, why we did it...what constitutes content?)

Docs fall into three categories:

references: what something is

application/procedurals: how something is done

theory: why something is done

Different end users need different categories for different purposes.

What makes good docs?

clear/concise (no longer than necessary, no fat)

complete/comprehensive (no "undocumented features")

correct

critical

tight / targeted / timely / thorough

re-useable????

Good docs make order out of chaos (visual: herding penguins dressed in all manner of national costumes)

"Nobody reads the docs...why should we care?"

What makes bad docs

incomplete

inaccurate

incoherent (bad grammar, bad logical flow)

inpenetrable (can't find what you need, jargon, engineer-eze,	poor indexing, don't know they even exist)

interminable (verbose, convoluted, chatty...too long)

How many===even one is too many!! (candy toss)

Who needs docs?

image of dad putting together a bicycle xmas eve...

person stranded on the side of the road not knowing where the spare tire is in the car

someone sitting in front of a computer screen/blue screen of death....

...who really needs docs -- everybody!

end users

support

sales

engineers

developers

management

Don't write bad poetry...write good docs!

Toothbrush example:

---a parts and materials list

---scheduling issues

---best practices and timeline

---variety of hardware and software available

---step-by-step procedures

---extras: floss, mouthwash

Shoelace install:

---hardware compatibility

---available platforms

---size of installation

---fresh install vs patch

---which version?

---notes, warnings, cautions

---threading

---knots

---lifecycle

We'll be glad to help:

online how-to's

word usage

style guides

editing

research

help with content delivery

write-up your processes

etc.

You can join in the fun, too::

write kbase articles

update and edit man pages

review package specifications

contribute to white papers

join the Fedora docs project

2005-11-07T16:55:09