writing effective self-help guides for world domination
DESCRIPTION
Developers write documentation. Technical authors write manuals. But in a perfect world, your users read software self-help guides. Consumers expect documentation to reflect the sophistication of the software they are using, and will abandon an application if they cannot easily find the answer to their problems. If we really want world domination of free and open source software, we need to have the self-help guides worthy of our code. In "Self Help Guides for World Domination" we'll take a look at the strategies and tools needed for really awesome documentation. Imagine a world where documentation actually helped you to find an answer, or solved one of your problems. If that sounds like a pipe dream, it's because you've had to struggle with too much crap documentation. Technical writing can be fun and accessible, but more importantly, it can be truly useful. By analysing how people use software, and where they stumble, we can drastically improve the experience our users have with our software documentation. Creating relevant documentation needs a little more than just a scraping of code comments though--and this talk will show you how it should be done. Open source tools for writing documentation are very sophisticated, but generally our mastery of them quite simply sucks. Whether they are using DocBook, Mallard or DITA, many projects have opted for very powerful markup languages for their documentation, but often use only a fraction of what the tools can do. Other projects have opted to go with Web-based content management systems and have failed to create a cohesive self-help experience for users. You will learn how to effectively use these common tools for creating and maintaining collaborative documentation. Real examples will be pulled from open source projects. If you've been wanting to help make the user experience better for your project, this talk is a must-see.TRANSCRIPT
WritingEffective SelfHelp Guides
for World Domination
www.hicktech.com@emmajanedotnet
AbstractDevelopers write documentation. Technical authors write manuals. But in a perfect world, your users read software selfhelp guides. Consumers expect documentation to reflect the sophistication of the software they are using, and will abandon an application if they cannot easily find the answer to their problems. If we really want world domination of free and open source software, we need to have the selfhelp guides worthy of our code. In "Self Help Guides for World Domination" we'll take a look at the strategies and tools needed for really awesome documentation.
Imagine a world where documentation actually helped you to find an answer, or solved one of your problems. If that sounds like a pipe dream, it's because you've had to struggle with too much crap documentation. Technical writing can be fun and accessible, but more importantly, it can be truly useful. By analysing how people use software, and where they stumble, we can drastically improve the experience our users have with our software documentation. Creating relevant documentation needs a little more than just a scraping of code comments thoughand this talk will show you how it should be done.
Open source tools for writing documentation are very sophisticated, but generally our mastery of them quite simply sucks. Whether they are using DocBook, Mallard or DITA, many projects have opted for very powerful markup languages for their documentation, but often use only a fraction of what the tools can do. Other projects have opted to go with Webbased content management systems and have failed to create a cohesive selfhelp experience for users. You will learn how to effectively use these common tools for creating and maintaining collaborative documentation. Real examples will be pulled from open source projects.
If you've been wanting to help make the user experience better for your project, this talk is a mustsee.
I talk about the popular stuff: Version Control,
Documentation
Writing Open Source● WOSCON 2009: the firstever open source
documentation conference● !wosdocs● #woscon
Documentationdoesn't have to be ugly
AND
We can makedocs hurt less.
This talk:● Types of documentation● Intended audience● Framework● Case study: StatusNet
Identi.ca tshirt slide
http://www.redbubble.com/people/karlcow/tshirts/31285191imidenticaandimopen
lizzie_anne http://www.flickr.com/photos/24498687@N03/2337550017/
Types of “Documentation”
● Dictionaries (function references)● Release notes● UI text● Case studies● Point of need cheat sheets● Inline help● Selfhelp guides● Marketing and promotional text● Cookbooks and HOWTOs
Types of “Readers”● Developers: people who are writing new
code; you six months from now● Existing users: administrators, end users● Marketing prospects
bobtravis http://www.flickr.com/photos/bobtravis/4005339850/
Cindy47452 http://www.flickr.com/photos/cindy47452/1500174297/
Framework Capture
Organize
TranslateOutput
Review
Revise
About the project
● out of date● Incomplete● hard to maintain● painful
Daniel Morris http://www.flickr.com/photos/danielmorris/147735447/
Wanted Documentation● Code base and functions● Community Wiki http://status.net/wiki/Main_Page● API documentation (a combination of functions yields an
XML output that can be used e.g. public timeline)● Developer Manual● Administrator Manual● User Manual● Online help● Plugins● I18N
Pink sherbert photography http://www.flickr.com/photos/pinksherbet/3372060864/
Challenges● Tie documentation to pain and pleasure. Make it easy to write
documentation by tying it in places where work is already happening.
● Make documentation useful and therefore more rewarding for the documentation contributors.
● Write only useful, taskfocused documentation.● Single source the "canonical" source of information. ● Automate where possible.
http://www.flickr.com/photos/martinlabar/2832969149/ Martin LaBar
The plan● Centralized documentation in a machinereadable format (XML).● Well documented code that is scraped and pushed to the Web.● Translation of documentation at the machinereadable stage.● Push documentation to communityeditable space.● Review and revise role that is responsible for pulling edits back into
the trunk and recommending UI fixes at “pain” points.● Write only useful documentation to accomplish specific tasks.
Who does this magic?● Developers document code →● Feature list in release notes →● Point of need: task list ("how do I..."). FAT,
not FAQ● Community adds to the wiki which is pulled
back into the code (fix UI where community edits show flaws in the codebase)
Rollout● The framework is used to describe the
structure for the whole documentation system.
● Product owner defines the standards for documentation. (Wasn't Evan clever to hire a crazy monkey that loves docs and version control and community and pirates?)
● The rollout involves: Capture Organize → →Output
http://www.flickr.com/photos/starscream_e/220892520/ chris starscream
Framework Capture
Organize
TranslateOutput
Review
Revise
http://www.flickr.com/photos/therichbrooks/2600080329/ therichbrooks
Capture
Capture● Brainstorm a list of all possible things that
people will want to do. Interview developers and community.
● Sort the task list by roles and prerequisite knowledge.
● Establish a culture of documenting code.
Framework Capture
Organize
TranslateOutput
Review
Revise
http://www.flickr.com/photos/curiousexpeditions/3394943117/
Organize
Organize● Put information into a single source system. Use a
machine readable language (XML of some flavour: DocBook, DITA, Mallard).
● Establish and apply relevant tags based on audience output.
● Always think about automation, efficiency and reuse. Never write something twice.
● At this stage translate your text and pull it back into the organization system (more about this...)
Framework Capture
Organize
TranslateOutput
Review
Revise
Translate
http://www.flickr.com/photos/opacity/284124471/
Translate● Push to translators while text is at the XML
level.● Bring back the translated text for output
processing.● TranslateWiki● See also: GNOME/Ubuntu projects
Framework Capture
Organize
TranslateOutput
Review
Revise
Output
Output● Push content to...● PDF● HTML● Community wiki● Etc
Framework Capture
Organize
TranslateOutput
Review
Revise
Review
Wasabi Noise http://www.flickr.com/photos/djkubik/192688574/
Review● Have a feedback mechanism in place
(comments, editable docs, rate+review)● Review changes for UI improvements that are
needed, changes and additions that can be rolled (as a patch) back into the source.
● Although there are tools to import back into API docs (https://code.launchpad.net/~paulivirtanen/scipy/pydocweb), hand rolling is probably better because you can look for things that should be fixed in docs, but in the UI.
Framework Capture
Organize
TranslateOutput
Review
Revise
ReviseRevise
Pirate Joey http://www.flickr.com/photos/pirateyjoe/3501692359/
Revise● Collate feedback for each language and
each vendor branch.● Return changes to the source with notes on
the changes from the previous version.● Translate and Publish the revised docs.● Improve the UI where relevant.
http://www.flickr.com/photos/starscream_e/220892520/ chris starscream
Framework Capture
Organize
TranslateOutput
Review
Revise
OMFG!That was awesome!
Sign. Me. Up!Writing Open Source 2010
www.writingopensource.com
StatusNet [email protected]
@emmajanedotnet
CC BYSANC