Lighting Talks¶
Write Tighter, Revisited¶
| Author: | Marcia Johnston, @MarciaRJohnston, http://howtowriteeverything.com/ |
|---|
Gave a talk last year, “Write Tighter”, and she wanted people to remember one thing: see be-verbs. (Not beavers.) “be”, “was”, “has been”, “will be”, “will have”, “been having”. Those are a flag that your writing can be tightened up, made more concise, made more engaging, and clarified.
But why?
It’s cheaper! Translations cost $0.25/word/language, so getting rid of “be-verbs” means you pay less. And you will be translating if you’re remotely successful.
And it makes your writing more readable.
Test the Docs¶
| Author: | Dirk Myers |
|---|
Partnering with other startups to use their SDK to develop applications to spec. This lets them effectively pilot the new user experience. What they’ve found is that the bugs filed aren’t at all what they expected. You know about prolems in your product that you think users will report, but they don’t. They want to know what’s next. So now they write the docs first. They write a doc, show it to customers, and ask what they’d do next, what questions they have, etc. And this is leading to increased customer happiness with documentation and reduced support costs.
Open Source Documentation, The Hard Way¶
| Author: | Anne Gentle, http://justclickwrite.com/ |
|---|
“I’m a unicorn: an extroverted technical writer.”
Half of the Open Stack documentation was written by 3 writers. Six months later, another half was written by 7 writers. That was a lot of work. But there were 130 documentation contributors overall. And when there are 910 overall Open Stack contributors, you have to wonder: am I getting the right contributors?
Ran a book sprint to write a 200 page book in a week. Flew in contributors who’d been operating Open Stack at scale for six months or more, and wrote the guide to Open Stack. And then O’Reilly asked if they could publish it (now 300 pages), since they were having trouble finding qualified authors. And now they’ve produced an Open Stack security guide, as well.
Applying developer techniques to documentation.
Write, Measure, Repeat¶
| Author: | Dan Stevens |
|---|
New to Atlassian, working on BitBucket. And they’re trying to change how they think about information solutions. One thing he doesn’t think Atlassian does very well is measure results for documentation. So they asked themselves, “How do we measure success with documentation? And how do we make that repeatable?” Beyond just writing something technically accurate, what are we trying to achieve?
“In the documentation, can we lead them from the software, to the docs, and back, to acheive a specific feature adoption?”
So now they’re rewriting tutorials, and measuring how many people are entering documentation, and then acheiving some business goal. [NB: Conversions.]
Measuring conversion lets you talk about documentation as more than just a cost center.
EPUB in a Nutshell¶
| Author: | Chuck, @chuckdude |
|---|
[Former O’Reilly editor]
EPUB is a website, packed in a folder, with some XML files. To “do” EPUB, you need to be comfortable with HTML, CSS, and some light XML. What EPUB? It’s portable, searchable, bookmarkable; you can copy and paste. PDF – the “pretty dead format” – is the bane of a lot of documentarian’s experiences. It’s great for presentation and dead trees, not for sharing.
How do you learn EPUB? Look at the source. Just unzip any EPUB file.
[Demo of what an EPUB contains.]
EPUB is pretty simple, and it’s incredibly powerful.
EPUB is managed by the IDPF (International Documentation Publishing Forum).