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
[email protected]
@Loquacities
Lana Brindley
Any questions?
