Podcast: Play in new window | Download

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

• La Crosse Technology WT-3126B Radio Controlled Aluminum Analog Wall Clock
• More La Crosse atomic analog clocks

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
    • phpDocumenter
    • Rdoc & Yard
    • Doctest