Writing a File Format Specification

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.

Suggestions for Writing Specs

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.

Suggestions for Good Technical Writing

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.