[RFC] design document template?
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
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
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:
One paragraph summary.
syntax summary or diagram
details of interface
motivation including alternatives rejected
blah blah blah
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.
More information about the bazaar