Jul 13 2010

Episode 77: Documentation

Play

Proper documentation of all kinds helps to make sure you don’t frustrate your users and spend less time doing support.

News/Follow-Ups – 00:35

  • Mark receives his Geek Tool
  • Internet woes

Geek Tools – 01:50

Webapps – 04:37

  • Boomerang – Include some javascript in your site and get back performance information.
  • Postmark – Web service for sending email from your application.

Documentation – 13:13

  • What to write?
    • Tech docs range from high-level overviews, to step-by-step walk throughs, to auto-generated docs
    • People learn differently
    • Users may be at different skill levels
    • Projects should have many different forms of documentation
  • Types of documentation
    • Requirements
      • What the program should or does do
    • Architecture and Design
      • Lays out the general design and reason for a specific functionality
    • FAQ
    • User centric
    • Technical
    • Automatically generated docs
    • README
      • How to install or compile
      • Copyright info
      • Known bugs
      • Most common troubleshooting techniques
      • Changelog
      • Credits
  • User Documentation
    • Tutorial
      • Be quick, a user should be able to accomplish something (even if small) in thirty minutes
      • The first tutorial should be fairly easy, you can always drill down or get into more difficult material later
    • Topical Guides
      • Covers a conceptual area, e.g. Models, sessions, controllers. etc.
  • Technical Documentation
    • Technical documentation is usually worthless, at best it is slightly better than browsing the source code
    • There is no substitute for hand written and edited documentation, even for reference material or APIs.
    • Tools