Your SlideShare is downloading. ×
0
Writing
Effective Self­Help Guides
   for World Domination


www.hicktech.com
@emmajanedotnet
Abstract
Developers write documentation. Technical authors write manuals. But in a perfect world, your users read software...
I talk about the popular 
  stuff: Version Control, 
     Documentation 
Writing Open Source
●
    WOSCON 2009: the first­ever open source 
    documentation conference
●
    !wosdocs
●
    #wosc...
Documentation
doesn't have to be ugly
AND
We can make
docs hurt less.
This talk:
●
    Types of documentation
●
    Intended audience
●
    Framework
●
    Case study: StatusNet
Identi.ca t­shirt slide




http://www.redbubble.com/people/karlcow/t­shirts/3128519­1­im­identica­and­im­open
lizzie_anne http://www.flickr.com/photos/24498687@N03/2337550017/
Types of 
          “Documentation”
●   Dictionaries (function references)
●   Release notes
●   UI text
●   Case studies
...
Types of “Readers”
●
    Developers: people who are writing new 
    code; you six months from now
●
    Existing users: a...
bobtravis    http://www.flickr.com/photos/bobtravis/4005339850/ 
Cindy47452    http://www.flickr.com/photos/cindy47452/1500174297/
Framework             Capture



             Revise

                                Organize

Review



                ...
About the project


  ●
      out of date
  ●
      Incomplete
  ●
      hard to maintain
  ●
      painful

Daniel Morris...
Wanted Documentation
●   Code base and functions
●   Community Wiki ­ http://status.net/wiki/Main_Page
●   API documentati...
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 wher...
http://www.flickr.com/photos/martinlabar/2832969149/ Martin LaBar
The plan
●   Centralized documentation in a machine­readable format (XML).
●   Well documented code that is scraped and pu...
Who does this magic?
●
    Developers document code →
●
    Feature list in release notes →
●
    Point of need: task list...
Rollout
●
    The framework is used to describe the 
    structure for the whole documentation 
    system.
●
    Product ...
http://www.flickr.com/photos/starscream_e/220892520/ chris starscream
Framework             Capture



             Revise

                                Organize

Review



                ...
Capture




http://www.flickr.com/photos/therichbrooks/2600080329/ therichbrooks
Capture
●
    Brainstorm a list of all possible things that 
    people will want to do. Interview 
    developers and com...
Framework             Capture



             Revise

                                Organize

Review



                ...
Organize




http://www.flickr.com/photos/curiousexpeditions/3394943117/
Organize
●   Put information into a single source system. Use a 
    machine readable language (XML of some flavour: 
    ...
Framework             Capture


             Revise

                                Organize

Review



                 ...
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 
...
Framework             Capture



             Revise

                                Organize

Review



                ...
Output
Output
●
    Push content to...
●
    PDF
●
    HTML
●
    Community wiki
●
    Etc
Framework             Capture



             Revise

                                 Organize

Review



               ...
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 im...
Framework             Capture


             Revise

                                Organize

Review



                 ...
Revise




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...
http://www.flickr.com/photos/starscream_e/220892520/ chris starscream
Framework             Capture



             Revise

                                 Organize

Review



               ...
OMFG!
        That was awesome!
           Sign. Me. Up!
               Writing Open Source 2010
              www.writing...
Writing Effective Self-Help Guides for World Domination
Writing Effective Self-Help Guides for World Domination
Upcoming SlideShare
Loading in...5
×

Writing Effective Self-Help Guides for World Domination

2,262

Published on

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.

Published in: Technology, Business
1 Comment
2 Likes
Statistics
Notes
  • This so rules you have no idea.
    Let me put it this way.
    Aristotle's Rhetoric breaks down into ETHOS (who you are), PATHOS (how you make folks feel with your words), and LOGOS (the info you're presenting & its importance).
    With HELPDOCS, you are creating stuff with 100% ETHOS.
    Your users already love you. They want to read more helpdocs if they are serious.
    All other marketing fluff is less important, because without ETHOS, it won't get listened to at all.
    Only HELPDOCS rule for 'what should you write today'. A bit of PR and marketing stuff too, but: always communicate MOST with your EXISTING USERS, and HELPDOCS have the perfect storm of ethos & logos - pathos is up to you.
    THANKS EMMA JANE !!! :D
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total Views
2,262
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
28
Comments
1
Likes
2
Embeds 0
No embeds

No notes for slide

Transcript of "Writing Effective Self-Help Guides for World Domination"

  1. 1. Writing Effective Self­Help Guides for World Domination www.hicktech.com @emmajanedotnet
  2. 2. Abstract 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.
  3. 3. I talk about the popular  stuff: Version Control,  Documentation 
  4. 4. Writing Open Source ● WOSCON 2009: the first­ever open source  documentation conference ● !wosdocs ● #woscon
  5. 5. Documentation doesn't have to be ugly
  6. 6. AND
  7. 7. We can make docs hurt less.
  8. 8. This talk: ● Types of documentation ● Intended audience ● Framework ● Case study: StatusNet
  9. 9. Identi.ca t­shirt slide http://www.redbubble.com/people/karlcow/t­shirts/3128519­1­im­identica­and­im­open
  10. 10. lizzie_anne http://www.flickr.com/photos/24498687@N03/2337550017/
  11. 11. Types of  “Documentation” ● Dictionaries (function references) ● Release notes ● UI text ● Case studies ● Point of need cheat sheets ● Inline help ● Self­help guides ● Marketing and promotional text ● Cookbooks and HOWTOs
  12. 12. Types of “Readers” ● Developers: people who are writing new  code; you six months from now ● Existing users: administrators, end users ● Marketing prospects
  13. 13. bobtravis    http://www.flickr.com/photos/bobtravis/4005339850/ 
  14. 14. Cindy47452    http://www.flickr.com/photos/cindy47452/1500174297/
  15. 15. Framework Capture Revise Organize Review Translate Output
  16. 16. About the project ● out of date ● Incomplete ● hard to maintain ● painful Daniel Morris http://www.flickr.com/photos/danielmorris/147735447/
  17. 17. 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
  18. 18. Pink sherbert photography  http://www.flickr.com/photos/pinksherbet/3372060864/
  19. 19. 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, task­focused documentation. ● Single source the "canonical" source of information.  ● Automate where possible.
  20. 20. http://www.flickr.com/photos/martinlabar/2832969149/ Martin LaBar
  21. 21. The plan ● Centralized documentation in a machine­readable format (XML). ● Well documented code that is scraped and pushed to the Web. ● Translation of documentation at the machine­readable stage. ● Push documentation to community­editable 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.
  22. 22. 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)
  23. 23. 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
  24. 24. http://www.flickr.com/photos/starscream_e/220892520/ chris starscream
  25. 25. Framework Capture Revise Organize Review Translate Output
  26. 26. Capture http://www.flickr.com/photos/therichbrooks/2600080329/ therichbrooks
  27. 27. 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.
  28. 28. Framework Capture Revise Organize Review Translate Output
  29. 29. Organize http://www.flickr.com/photos/curiousexpeditions/3394943117/
  30. 30. 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...)
  31. 31. Framework Capture Revise Organize Review Translate Output
  32. 32. Translate http://www.flickr.com/photos/opacity/284124471/
  33. 33. 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
  34. 34. Framework Capture Revise Organize Review Translate Output
  35. 35. Output
  36. 36. Output ● Push content to... ● PDF ● HTML ● Community wiki ● Etc
  37. 37. Framework Capture Revise Organize Review Translate Output
  38. 38. Review Wasabi Noise  http://www.flickr.com/photos/djkubik/192688574/
  39. 39. 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.
  40. 40. Framework Capture Revise Organize Review Translate Output
  41. 41. Revise Pirate Joey http://www.flickr.com/photos/pirateyjoe/3501692359/
  42. 42. 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.
  43. 43. http://www.flickr.com/photos/starscream_e/220892520/ chris starscream
  44. 44. Framework Capture Revise Organize Review Translate Output
  45. 45. OMFG! That was awesome! Sign. Me. Up! Writing Open Source 2010 www.writingopensource.com StatusNet ­ emma@status.net @emmajanedotnet CC BY­SA­NC
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×