26th
Tables -- an underused weapon in the computer author's arsenal
Many of my authors (you know who you are) insist that their books should consist entirely of prose and code, perhaps punctuated with the occasional heading.
If you insist on this, then you are doing yourself and your readers a disservice.
Use tables to provide readers with quick reference information. Most tables need three columns:
- Icon / menu item / parameter name — this is the thing that appears on screen, or will appear in the reader’s code, and that you want to explain to them. Example: “File | Print…”
- Brief description — this gives the reader a quick ‘here’s what the function is for’. Example: “Displays a dialog from which you can print your document.”
- Longer description / use — here you can give the reader useful information that will help them make good use of the feature. Example: “The dialog lets you choose how many copies to print, and if you don’t want to print every page then you can choose the pages you’d like. If you just want to print the whole document then you can click OK as soon as the dialog comes up — you don’t have to even look at it.”
Usually REFERENCE information should come after the ‘instruction’ part and the ‘understanding’ part of a topic. Readers want reference material when they understand the concept, and want to try doing something a bit different. (For example you can’t learn English from a dictionary, but once you know the basics of English then flicking through a dictionary can teach you a lot more. That’s the function of reference — to give the educated the info they need to get even better.)
Tables fill up pages quickly, give immediate value to a reader, and are easy to write. Use them!