[PD] documentation (was: DSP abstractions)

Mathieu Bouchard matju at artengine.ca
Tue Jun 19 22:45:46 CEST 2007


> A bridge with automated service discovery could be nice, but I fear that 
> it may also be too much bureaucracy and in the end may not help,

I would especially like to say, beware of the bureaucracy and anything 
that looks like it. It has to do with what the values of pd are:

$1 = nice colours

$2 = nice layout

$3 = helppatches have consistent colours and layout

$4 = helppatches have consistent structure: every section that is supposed 
to be in every helppatch has at least something written in it

$5 = helppatches are kept up to date

$6 = helppatches communicate concisely, minimising the boilerplate 
copypasting that you have to learn to skip over in order to get to the 
actual information

$7 = helppatches communicate the intent and the spirit of pd

$8 = helppatches are complete, communicating everything you may have to 
know about pd

So far, PDDP emphasises the top of the list. If I were (or rather "when I 
will be") taking care of documentation I'd concentrate on the bottom of 
the list.

I especially don't care about PDDP because it emphasises $1,2,3,4. By 
emphasising $1,2,3,4 it makes $5 that much more difficult and especially 
it makes it boring. At least if you're writing tricky documentation and 
you don't like writing documentation you can have a sense that you're 
doing something tricky which uses your intelligence, whereas applying 
$1,2,3,4 is not. Item $4 is especially infuriating because it puts the 
respect of top-down rules of documentation more important than effective 
communication, which may (and will) conflict with $5,$6,$7,$8, especially 
if $4 doesn't doesn't include provisions for straying away from mere 
form-filling.

To be fair, $7 is partially covered by the "all about" patches, but it 
could be a lot more than that, especially considering $8.

I would continue with $9, $10, and more important values that are 
completely foreign to PDDP, but this email is already long enough.

> That help-patch may be quick and dirty, but it must *exist*.

That's very $8.

> And a service discovery bridge may also be built later as a decorator 
> abstraction itself around the original abstractions.

You mean like http://en.wikipedia.org/wiki/Decorator_pattern ?
(original page at http://www.c2.com/cgi/wiki?DecoratorPattern )

  _ _ __ ___ _____ ________ _____________ _____________________ ...
| Mathieu Bouchard - tél:+1.514.383.3801, Montréal QC Canada


More information about the Pd-list mailing list