Writing Effective Self-Help Guides for World Domination
3 likes1,745 views
The document discusses the importance of creating effective self-help guides for software documentation to enhance user experience and ensure usability in free and open-source software. It emphasizes the need for well-structured, task-focused documentation that utilizes powerful documentation tools effectively, while also encouraging community collaboration and feedback. The content provides a framework for capturing, organizing, translating, and reviewing documentation, aiming to improve the overall quality and accessibility of technical documents.
Writing Effective Self-Help Guides for World Domination
- 1. Writing Effective SelfHelp Guides for World Domination www.hicktech.com @emmajanedotnet
- 3. I talk about the popular stuff: Version Control, Documentation
- 4. Writing Open Source ● WOSCON 2009: the firstever open source documentation conference ● !wosdocs ● #woscon
- 6. AND
- 8. This talk: ● Types of documentation ● Intended audience ● Framework ● Case study: StatusNet
- 11. 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
- 13. Types of “Readers” ● Developers: people who are writing new code; you six months from now ● Existing users: administrators, end users ● Marketing prospects
- 16. Framework Capture Revise Organize Review Translate Output
- 18. About the project ● out of date ● Incomplete ● hard to maintain ● painful Daniel Morris http://www.flickr.com/photos/danielmorris/147735447/
- 19. 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
- 21. 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.
- 23. 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.
- 24. 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 code base)
- 25. 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
- 27. Framework Capture Revise Organize Review Translate Output
- 29. 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.
- 30. Framework Capture Revise Organize Review Translate Output
- 32. 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...)
- 33. Framework Capture Revise Organize Review Translate Output
- 35. 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
- 36. Framework Capture Revise Organize Review Translate Output
- 37. Output
- 38. Output ● Push content to... ● PDF ● HTML ● Community wiki ● Etc
- 39. Framework Capture Revise Organize Review Translate Output
- 40. Review Wasabi Noise http://www.flickr.com/photos/djkubik/192688574/
- 41. 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/~pauli virtanen/scipy/pydocweb), hand rolling is probably better because you can look for things that should be fixed in docs, but in the UI.
- 42. Framework Capture Revise Organize Review Translate Output
- 44. 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.
- 46. Framework Capture Revise Organize Review Translate Output
- 47. OMFG! That was awesome! Sign. Me. Up! Writing Open Source 2010 www.writingopensource.com StatusNet emma@status.net @emmajanedotnet CC BYSANC