Technical Writing

for hoopy open source froods

who really know
where their towels are

Me

* Why am I qualified to tell you this?* Wont bore you with resume* Bachelor of Business, Marketing and Info Sys majors* Ran own business* Got MBA* Been writing for Red Hat for three years

What is this documentation stuff anyway?

* Learned how to write at 5 or 6. At a passable level.* Why write better? Allows people to access code.* written material that describes a product.* user manuals* design documents* brochures/handouts* slide decks* release notes* errata notes* code comments* reference guides* installation guide* product packaging* websites* FAQs* --help text* man pagesAll writing is marketing

Why Document?

* Good docs reduce support calls. * Small team only has one or two people to answer calls, who are better off doing other things.* Big companies, reduces wait times, happier customers.* Company doesn't have to hire lots of people to explain how to turn it on, and customer can find the answer for themselves

Who Does?

* Now we know what documentation is, who is it for?* No-brainer* A few broad categories

Users

* want to use product to achieve their goals* need easy to understand instructions* need clear descriptions* need info in a variety of presentations

Contributors

* Any person with an interest in the project how to use it, how it works, what functions, question for the answer to the ultimate question* could be seasoned open source devs or hapless university students looking for very first project* need to get program installed, get source code, work out whats happening. And fast.

Developers

* might seem as though they should know* codebase grows, number of contributors grows, need to keep up with changes.* code commenting is most important to devs

So ...

What's in it
for me?

* Good question, answer depends on who you are and what youre planning to do* If youve spent best years of your life developing then you want people to know about it* Want people to be able to work it* Want them to find you* Pick up where you left off

Getting started on the rollercoaster of docs writing* Even if youve never written anything more than a shopping list before, tech docs can be written by anyone who can follow a development process.

Information Plan

Content Specification

Writing

Translation
&
Production

Review

`Release

5 Phase Model by JoAnn Hackos

* Model used at Red Hat* developed by JoAnn Hackos* waterfall model each step flows to next

Planning

10%

* You need a plan* Define audience* Define SMEs* Most important key dates: first draft, reviews, translation, final draft, publication* Percentages help with planning proportion of whole project

Content Specification

(Isn't there some rule about cats in presentations?)

20%

* Decide whats going in to the book (a cat?)* Get in contact with SME and nut out an outline* Hopefully other docs exist too wiki or website, mailing list archives, blogs or docs others have written, code comments* Chapter and section headings, and link each heading to some kind of source material* Re-evaluate plans to number of chapters

Writing

50%

* got schedule, got content, now to write* create book and chapters, fill with content* more hints on writing well coming up* finish first draft, read over then send to dev team for tech review* RH does tech review, product QE, docs QE, and peer review.

Translation

19%

i18n

L10n

g11n

* Its written, you think its pretty good; dev team says its good, QE have passed it. Now to translate.* RH translates into ~23 languages (varies)* trick is to have book as close to complete as possible in original lang (en-US)* Sometimes translations lag, mostly on time* L10n translation* i18n making s/ware compatible across languages* g11n - both

Review

1%

* call with project manager, senior developer, SMEs, and anyone else who cares

Maintenance

* nature of s/ware particulalry open source that it changes with every release.* your project should have a ticketing/bug system to allow ppl to flag issues in docs* go through every book before release, and ask them to be reviewed by SMEs* longer with one project means more maintenence. Eventually will hit critical mass and explode

What happens when things ...

GO
WRNOG?

* MMF story: ... three months had passed, my SME had vanished into the ether, I had no book and a useless wiki. I started to panic.

* You saw that coming didnt you?* When a writing project starts to fall apart, run around in circles screaming. Then grab your guide, and make sure you have your towel. * Fall back on your plan.* Writing docs shouldnt be a black box* Waterfall model gives the writer a framework, and helps the process become transparent* Allowed me to go back and say you saw this, you signed off on this. Decision reached to pull book, without blame landing on anyone.

You
need

tools!

* Promised more info on writing well* wrap processes around writing, but it still needs to be about getting words on paper* Ppl dont want to snuggle in bed with a manual* Need to hit points without being encyclopaedic* Interesting without being wordy/joking* give reader info without being dry* heres my toolbox ...

Get

organised

* Be organised, have a plan, but also be flexible.* Consistently review the plan* Douglas Adams love deadlines/whooshing sound* How long to write a novel? 3 novels in less than 30 days each* If you have a deadline, you have motivation to get stuck into the writing and get it finished on time.* If not on time, at least youll have prepared an excuse

Choose
your
voice

* Know your audience, so you know how to speak to them* Manual for 1st person shooter relaxed style, a bit of humour.* Install guide for enterprise software more formal, remove tongue from cheek

Say what you mean

* Dont say Take heed of the fact that in some cases there may be airborne heated bread cooking apparatus".* People will get bored and switch off* Don't say "There may be a risk that"; "There is a possibility that"; "In some cases, there is a chance that". Say "Sometimes". That's it.* IT industry loves deployed. Networks, systems, software, workstations, lunch. Say installing, setting up, distributing. Deploy is too vague.

Use short sentences

* Nobody wants to read your flowery poetic language* Likely to get bored and go do something else* Tech docs short. Publish on web even shorter* Average around 10-20 words harder than it sounds* OK to mix it up for interest* 91 word long sentence, came from intro to book about rope

Don't be

A pretentious jerk

* Harder to do than it sounds* When doc is formal we tend to choose big words to make it sound fancy or make us look smart* Just makes writing hard to read and can lead to some interesting mistakes:* enumerated for found or discovered* Utilising when you mean using* provided for prove (nothing will ever provide to be true)

A word about

passive voice

(and cats)

* Hallmark of pretentious writer is passive voice* Dont understand it? Many dont* Tricky can be hard to spot. Good news if hard to spot, dont need to worry about it* Sometimes passive is OK. Change obvious ones* Basic structure subject->verb->object (cat sat on mat)* Reverse is passive* See what happened to verb?* Two word verb means something is up* Look for keywords is, are, been, was be, were, being.* was written, be operated, are enabled.

Cut out the cruft

* Dont write 3 sentences explaining something in 3 ways* Look for words like for example, such as, specifically, namely.* If you need to add something to your sentence to explain it, then youve done something wrong. Re-write the sentence.* Re-read and make sure each sentence is a single idea and isnt repeated. * Take down to word level.* My Little Pony comb accessory* weather event, emergency event, basic fundamentals. Word pairs that are better off as single words* Get rid of redundancies

Where theres a will ...

Theres a way to rewrite it

* will ought to be struck out of the English language. * if you press the red button, the rocket will take off. No it wont. If you press the red button, the rocket takes off. Even better: The rocket takes off when the red button is pressed.

* Incidentally, so should may. It has two meanings. Pick might or can.

Read what you write

* Read once through without stopping look for structure, flow, and overall feel.* Read through backwards slowly look for odd sentences and strange structure.

* Read what is actually there, not what you think is there* Read out aloud find things that dont sound right, and helps to place punctuation* Read backwards helps to read whats on the page. Especially good for short texts School executions

Final and most important always know where your towel is.

Now grab your peril-sensitive sunglasses ...

+61 410 500 659

lanabrindley@gmail.com

@Loquacities

Lana Brindley

Any questions?