×
  • Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
 

Writing Effective Self-Help Guides for World Domination

by Technical Author and Trainer at Owen Sound, Canada on Oct 26, 2009

  • 2,969 views

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

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.

Statistics

Views

Total Views
2,969
Views on SlideShare
2,958
Embed Views
11

Actions

Likes
2
Downloads
26
Comments
1

1 Embed 11

http://www.slideshare.net 11

Accessibility

Categories

Upload Details

Uploaded via SlideShare as Adobe PDF

Usage Rights

CC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike LicenseCC Attribution-NonCommercial-ShareAlike License

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel

11 of 1 previous next

  • spineofgod Srini Kumar, Founder at TinyVox.com 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
    1 year ago
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Writing Effective Self-Help Guides for World Domination Writing Effective Self-Help Guides for World Domination Presentation Transcript