If you are going to write a graphics file format specification, the
first thing to do is to make a list of the types of information you
are going to store. Then make a second list, of all the auxiliary data
a program will need in order to render the data you wrote down in the
first list. Get the picture? In compiling the second list, you'll
almost certainly find that you forgot something in the first--and
vice versa.
The next thing to do is to look at all the format specifications like
yours and notice where the writers went astray. Now go back and fix up
your list. Now iterate. This is an exercise in honesty, intelligence,
and diligence. Nobody--and we mean nobody--has gotten it right
yet. Maybe you'll be the first.
When you read through your pile of format specifications you'll find
out that no two are alike (unless they are written by the government
or military--in that case they are all
alike). And you will discover that most are poorly written and quite
complex as well. How can you avoid making the same mistake? Here are
a few suggestions.
- A large spec needs a table of contents, a
bibliography, and an index. However, because most specs are usually
no more than a dozen pages or so, most will not need to have this
type of organization.
- On the spec's cover sheet, give full information about
your company, any products associated with the format, the format
version, date of release, where the latest copy of the spec may be
obtained, and how developers may get in contact with you to ask
questions.
- Detail the full history of the spec, including the
differences between the current version and all previous versions,
and not just the dates of its revision. Tell why the format was
created. Detail some insights of how it was designed. Speculate on
what features future versions might contain. And give the names of
your developers and other people involved. Show the human thought
that exists behind the cold chunk of data that is your
format.
- List the features of your format and explain how you
intend that it should be used and not used. Give a rationale for
excluding features that people might find desirable (e.g.,
supporting multiple images, popular methods of data compression, and
so on). Give the developer reasons why she should use your format
(and why she should not bother with others).
- Include both block diagrams and
ANSI C code examples of the format's internal
data structures. Illustrate actual examples
of ASCII file format data and hexadecimal dumps
of binary format data. Such information helps programmers quickly
and correctly implement code that uses your format.
- If your format includes one or more forms of data
compression, error checking, encryption, etc., place this
information in a separate section, and give plenty of examples (both
written and code) of how these algorithms work. Include mathematical
formulas if you believe that they will make the concepts
clearer.
- Make the specification available in both hardcopy
and electronic form. The hardcopy version should be formatted as a
technical document using a font that won't degrade badly when the
spec is photocopied or faxed. Use a standard sized page layout so
the spec isn't a hassle to fit in an envelope when mailed. The
electronic version should be available as both
ASCII text and PostScript files. Making the spec
available in a word processing format (such as Microsoft Word or
FrameMaker) is nice but not absolutely necessary.
- Consider making a developer's toolkit for your
format. A collection of benchmark graphics files (one of each flavor
of your format) and a parser written in ANSI C
that reads and writes your format will be of tremendous help to
programmers. Such a kit will allow developers to implement your
format quickly in their products and will help minimize the chances
of numerous software packages appearing that create graphics files
that don't meet your spec. Examples of formats with toolkits include
TIFF, TGA,
WPG, and PNG.
- Submit your specification to every
FTP, Gopher, and Web site, and to every
BBS that archives file format specs. Notify the
maintainers of related FAQs (graphics, animation,
multimedia, audio, medical, etc.) that your format exists, and ask
for a mention. Send your literature to graphics and imaging software
companies to sell support of your format and/or software
products.
Examples of some well-written format specs that we've encountered
include TGA, TIFF, PNG, EPSF, and PostScript.
We've also found that some specs are well-written, but contain so much
extraneous information that they are overly complex and too tedious to
read. Most government and military formats are in this group, as are
those created by committee; examples in this category are
CALS, NITF,
NAPLPS, IGES,
GKS, and CGM.
And finally, format specs such as PCX, GIF,
JFIF, and Sun
Raster definitely fall into the "don't let this happen to you"
category.
Here are a few, more general,
guidelines on good technical writing:
- Write in a tutorial style with explanations and
examples of your topics. Don't just give a terse, dictionary
description of a topic that will leave readers confused and in need
of more information.
- Write in simple terms. Don't assume that your
readers enjoy 70-word sentences or that they have advanced degrees
in mathematics or computer graphics.
- Have other people read and attempt to understand
your spec. Don't assume that just because you understand what
you've written, every other reader will as well. You, as the file
format specification's author, understand the format inside and
out. Your readers, however, do not. Your job is to bring them up to
speed. Don't be embarrassed if you don't know how to do this; good
technical writing is a highly specialized skill. An explanation that
seems clear to you may be just gibberish to your readers. Get
help with your writing if you need it.
- Write for a world-wide audience of programmers. Omit
slang or regional expressions that a developer living on the other
side of the planet might not understand.
- Remember that programs that check spelling and
grammar are our friends. Use them.
Copyright © 1996, 1994 O'Reilly & Associates, Inc. All Rights Reserved.