Documentation for designers story

By Donald Jenner

Documentation is the most important kind of writing a professional -- an architect, an engineer, a designer, in particular -- does.  Documentation presents and sells a project.  As the project develops, documentation plots its growth, including changes.  Project design elements are integrated with related information, such as project scheduling and costs, and comments about decisions taken which have influenced the project.  At completion, the project documents are a foundation for maintenance.  In short, it'd better be done right.  With the range of powerful desktop publishing tools available -- both "page composition" and "wordprocessors" -- it is fairly easy to do so.

Project documentation combines different kinds of information; the required foundation is an integrative operating environment.  Most microcomputer platforms used in design projects offer such environments.  Vendors targeting the Unix workstation market have developed what might called "family solutions" -- packages of related products which work together, but often have only limited connection to products from other vendors.  

Macintosh systems offer good cross-product compatibility, by and large, but multi-tasking -- which makes it possible to run several applications at one time, and combine information on the fly -- is not reliable.  This should improve when the long-awaited System 7 comes out, and Mac-vendors get around to producing a range of compliant applications.  As it is, most of what this story says applies equally well to Macs and PC-family machines; the bias towards the latter group reflects more our prejudices and familiarity which comes from doing most of our work -- especially CAD -- on them.

The advent of Microsoft Windows 3.0 makes things substantially better for Intel/PC-family users.  A range of tools from many vendors, integrated in the incredibly popular Microsoft environment, combines to make the mechanics of documentation fairly simple.  

Windows-based documentation tools are a powerful adjunct to already familiar design tools.  These tools fall into three groups:  First, there are the project-planning tools proper.  These fit together with presentation tools and writing tools, as well as the more obvious design tools in an almost seamless fashion.  The result is that even small shops can offer polished complete projects with the same facility as the big shops.

To test different strategies, my associates and I chose what counts as a mid-range professional system -- the kind of system that would be equally appropriate to a small firm or a larger operation.  

The main design system is IBM's Model 80, equipped with an 8514 display system (adapter and monitor); this is a modest 386 machine.  It sits on a network to share peripherals and files with other machines; we use Artisoft's Lantastic proprietary boards and network operating system, now available both for AT-buss and MCA.  Artisoft also offers an ethernet variant of Lantastic.  The principle advantages for small shops are low cost, minimal memory requirements in a peer-to-peer configuration, and extremely simple setup and management.  

Image input -- "real world" pictures needed to show designs >in situ< -- was done using Epson's ES300C, which has the virtue of using standard parallel I/O rather than the more expensive GPIB variant.

Hardcopy output was to Hewlett-Packard printers:  We used HP's LaserJet III in native mode and with HP's PostScript cartridge to examine the advantages of each; we also tested Zenographics' SuperPrint, as an alternative printing strategy.  For color -- both presentation materials and proofs -- HP's PaintJet proved a modestly priced choice offering remarkably good results.  [For more on printers, see the accompanying story.]  We used a range of software products, described here and in the accompanying sidebars.

Project documentation begins in assembling information.  The design may be the heart of the matter, but such things as scheduling and costs are very close to the center.  Writing software proper serves as a composing tool, adding order and annotation to the basic information.  [For more on information management software, see the accompanying sidebar.]  

A design project generally takes time to mature in the designer's mind; the same is true for its description -- these are two faces of the same creative project.  As information comes together, let it "roll around" in the back of your mind for awhile.  This is an element of the writing process that seems to get skipped in general education, but it may be the most important thing one can do.  It is as if the mind "processes" along in the background, letting the more or less "raw" information slip into its correct places.  It doesn't hurt to verbalize some of the ideas -- personally, I find my morning shower is an ideal time for such a review.  My students think this is a bit peculiar; on the other hand, those who've tried it report good results....

It takes about two weeks for most people to reach the point where the gathered information has sorted itself out.  When the organizational ideas start perking up to the top of the mind -- as it were, on their own -- jot them down.  The purpose should be to make a list of main points, more or less in order.  A grand outline, the sort of thing that is taught in grade school writing classes, is >not< the objective.  Such outlines are generally overkill.  

These "talking points" listed, it is time to face the technical problems of writing.  Think carefully about style.  Depending on the kind of writing software chosen, you'll want to set up the basics -- headers and footers, topic headlines, tabular presentation formats, paragraphing and the like, as well as body text and fonts -- right at the beginning.  Store these in style sheets.  >Never< throw them away; this is the way in which a company defines its presentation "image" and if well done, it can really lend power to on-going relationships.

We find it useful to be choosy about fonts.  Body text is usually printed in 10pt type.  It is almost a convention.  In this size, a serif'd font (the kind with the little thingies on the ends of letters...) works well.  The serifs help the letters group better as the eye scans them, making for easier reading.  Since we are a bit old-fashioned, and favor text justified on both sides (which is supposed to be less readable), this is our concession to the reader.  We use the same font -- usually Times Roman or Palatino, less often Century Schoolbook -- in italics for picture captions.

To set off topic and sub-topic headlines, we use a sans-serif font, commonly Helvetica or a variant of Avant Garde.  The purpose is to startle the reader a bit, as a cue that something is about to happen.  Another trick can be played on the reader:  Set the headlines to large-and-small-caps.  The combination of capital letters serves the same purpose as bold-face.

We also like lots of pictures.  We commonly use both scanned bitmap images and computer-generated images, combined as needed.  For us, the best rule is to pick the pictures first.  If images have to be combined, we do this in an illustration program to test the combination, fine-tuning it before mixing with text.  These images can often be directly imported into PageMaker (it reads many illustration file formats directly).  The same images, in color, can be printed to a Canon color laser copier (which doubles as a printer) in small runs for as little as $1.00 each, and bound into the final, otherwise black-and-white "leave-behind" documentation.  The same images can be processed as video, computer or 35mm-slide shows.  This lends real pizazz to presentations; it also gives a sense of how a creative person or team envisaged a project at the beginning -- useful to those coming later.

Generally, we have found it easiest to "paste down" the pictures we have chosen first.  This is a tad easier in a page-oriented program, but the differences between such programs and high-end wordprocessors are decreasing rapidly.  The reason for this first step is simply to help gauge the way the text must flow.  A less formal "look" might feature the pictures, and wrap the text around them in one way or another.  For marketing pieces, we favor a style of two columns, with text in one and pictures in the other, often alternating which is on what side of the page.

For more formal documentation, we also use two columns.  We use a wide column for body text and major topic headers.  Subordinate points are noted in the left-hand, narrower column, adjacent to the supporting text.  Pictures are inserted in the body, with captions in italics.  This format serves well for technical documentation, where hype is less important than clarity.

With the styles determined and the pictures chosen and located in roughly the right order and place (subject to fine-tuning as one goes along -- the glories of electronic writing...), writing becomes largely mechanical.

Begin with an introduction; it simply states the purpose of the work and the presuppositions that apply.  Then tell the story, covering each major point.  Use the pictures to prompt the development of the subordinate points in each major topic area.  Experience suggests that good documentation has a picture (or table, or line drawing) on each page.  That works out to one paragraph per captioned picture in a marketing piece, and not much more than three paragraphs per picture in more technical documentation.

There is another hint which comes from experience:  Leave enough time for the job.  It is almost always evident when writing is forced.  Judging how much can be written in a session varies from person to person.  I find I can compose eight or ten pages at a time when I'm "hot."  My wife and partner finds this much writing difficult in a single session.  The rule should be something like, when it gets boring, or when it is not easy to see the next point, stop!  Go do something else -- or chill out with a beer or a soda and a racy novel.  Then come back the next day, and pick up.  The main points remain the same, and the prompts -- pictures, diagrams, tables -- are already in place to remind one of the next item on the agenda.  On the other hand, don't skip a day; that can cause one to lose the rythmn of writing.

When the basic draft, with the basic layout, is finished -- that's when to take a few days away from the writing project.  After three or four days, come back and critique the job you've done.  The writing will want some fine tuning, and the layout may seem a trifle off.  These are fixable.

It may also be appropriate to pass the text through a grammar checker (as well as a spelling checker, which should go without saying).  These grammar checkers are not perfect; there is no substitute for a sense of one's own writing style and the permissable flexibility in grammar (well, English grammar, anyway...).  But they can help analyze text, and allow for a "second opinion."  I particularly like the analysis Reference Software's Grammatik offers, of grade-level and complexity; it keeps me from sounding too much like the former professor I am.

The end result is a series of files on the machine, and some printed material.  As the project develops, the series of files grows,  They can be recomposed, or simply chained end to end at project completion.  Coupled with the basic information in the project data files -- spreadsheets and time-management tools -- it is very easy to know just where you've been.  This is good for you in later projects, and it is very impressive to clients, who have some idea why you're on board -- and cost so much.

###