[RFC] design document template?

[Ian Clatworthy]

Robert Collins wrote:
> Do you think one would be useful ? I think they can become too
> proscriptive myself, but on the other hand I was just thinking I'd like
> to encourage everyone to include a Motivation section for things they
> write...
> 
> -Rob

Yes, I think one is useful, even if it is treated as a checklist of
things to cover.

When the design is more of an "Interface Spec", my preference is for
something very domain specific, e.g. the interface spec for a GUI tool
needs to cover particular things while those for command line tools,
file formats, web-sites, reports, device drivers, etc. ought to cover
different things.

For more general design, a more general template is fine IMHO. I find it
useful to write the design doc as if it will become the technical
reference later. Call it laziness if you will. :-)

Partially based on man pages, one general design doc template I like has
sections something like this:


Name Type
=========

Purpose
-------
One paragraph summary.

Interface/Synopsis/Architecture
-------------------------------
syntax summary or diagram

Description
-----------
details of interface

Implementation
--------------
internal stuff

Rationale
---------
motivation including alternatives rejected

Examples
--------
blah blah blah

See Also
--------
whatever


FWIW, this "nests/chains" quite nicely so one document can have a top
level "entity" covered first, followed by any number of these, one per
sub-entity.

I'm not saying you should use the above BTW: just throwing the sort of
thing I've found useful in the past into the ring to trigger discussion.

Ian C.