[RFC] design document template?

Ian Clatworthy ian.clatworthy at internode.on.net
Tue Jun 19 07:19:09 BST 2007

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

One paragraph summary.

syntax summary or diagram

details of interface

internal stuff

motivation including alternatives rejected

blah blah blah

See Also

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

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.

More information about the bazaar mailing list