A piggy bank of commands, fixes, succinct reviews, some mini articles and technical opinions from a (mostly) Perl developer.

Jump to

Quick reference

Documentation formatting, presentation and distribution

Points relating to formatting and presentation (not content):
  • Documents need version numbers. This comes for free with a wiki-based system.
  • Need a "changes" section at the top, including dates & authors.
  • A table of contents with clickable (and bookmarkable) links
  • Code samples to be in a consistent style, monospace font, and limited to a single page
  • Web page or PDF, not .docx because .docx will be formatted differently by every application, and might appear corrupted or unreadable on some computers.
  • Host the document on company servers and send around a link to download it. Don't email as an attachment because it will become out of date quickly.