[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