Today, I heard from hacker news, of an excellent website with UNIX tutorials and Perl code examples. The web-dev context is kind of dated, but the UNIX stuff is still good: UNIX hasn’t changed much since the 80’s so UNIX tutorials don’t age.

I also found an excellent piece of advice for technical writing, i.e., the teacher-student relationship:

Understanding the Characteristics of a Student

The first thing that we need to understand before we start writing about some technical issue is that our reader has a few general, stereotypical qualities which we would do well to incorporate into our documentation strategy. The following list reviews some of the characteristics which will greatly direct your writing.

• Students think that what you have to say is boring
  • Incorporate pictures into your text. If it looks fun, it is fun.
• Students are intimidated by what you have to say
  • You may be extremely familiar with your product, class library, or code base, but that is because you’ve been working with it for the last few months. Remember that your reader is probably coming at this for the first time.
  • Tell some jokes. Get things off on the right foot. Make the reader feel as if you appreciate the struggle she has agreed to undertake.
  • Use lots of metaphors to explain things. It is likely that the ideas and theories you want to get across correspond to some daily activity that your reader can instantly feel empathetic with.
• Students are unfamiliar with terminology
  • For goodness sakes, make sure to include more description than seems reasonable to you. The advanced reader can skim through it and the beginning reader cannot live without it.
  • Make sure you leave enough time to compile a good index, table of contents and glossary. If you’ve been a reader of technical documentation you’ll know that these “extras” are sometimes the most utilized resources. Nevertheless, most authors skim through them at the last minute before printing.
• Students are insightful, give them a way to send feedback
• Students learn by doing.
  • Only in theory do people learn by theory. In reality they learn by example and participation. Make sure to give them a lot of code to work through. Include the theory in between the lines. Sneak it in so they don’t realize they are learning abstract concepts.
• Students have a problem
  • Your readers did not pick up the documentation to learn about the product. They picked it up because they needed to do something with the product. Thus, make your examples useful. Make them cut and paste problem solutions. Takes some time to predict the types of things that your customers will be doing with your code and solve those problems as examples.