Our Emperor Sponsors

  • InternetNZ
  • Google
  • IBM
  • HP

<-- Back to schedule

Writing Effective Self Help Guides for World Domination

Time:13:30 - 14:15
Day:Friday 22 January 2010
Location:Ilott Theatre (Town Hall)
Project: Writing Open Source

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.

Emma Jane Hogbin

Emma Jane Hogbin has been working as a web developer since 1996. Her infectious enthusiasm and ability to explain concepts without using technical jargon puts even the greatest technophobes at ease. Passionate about helping people to acquire knowledge, Emma Jane volunteers with the Drupal and Ubuntu documentation teams, has co-authored a best selling book, Front End Drupal, and has written several articles for Linux Pro Magazine. She is a former coordinator for The Linux Documentation Project and co-founder of the Writing Open Source initiative (

Well-known in the open source community for her technical knowledge, Emma also uses her enthusiastic Canadian humour to bring open source to a wider audience…such as the Drupal socks and their GPLed pattern. Through her consulting company HICK Tech, and at conferences around the world, Emma Jane has inspired people to overcome fear, uncertainty, and doubt and to tackle problems head-on. She chronicles her adventures at