[PD] Patterns for Pd Documentation

[Alexandre Torres Porres]

Em ter., 25 de mai. de 2021 às 05:50, Dan Wilcox <danomatika at gmail.com>
escreveu:

> Does anyone have a link, etc to the pddoc project/external from
> Pd-extended?
>
I feel a lot of this was already approached over 10 years ago but not
> ported over into Pd vanilla. It might be worth checking it out before
> starting from scratch.
>

this? => http://puredata.info/dev/pddp/pddp-drafts


> Also, keep in mind that old habits may be hard to break so don't be
> surprised if enforcing "one pattern to rule them all" might become
> "whack-a-mole."
>

:)

> To point some examples of things already done in regard to better
documentation:
 > - Porres' ELSE documentation and the Live Electronics Tutorial are good
because of
> the care to register and create patches that are visually unified, that
show a concern
> with good practices of patches creation.

Thanks for the compliments.

Well. For ELSE and Cyclone I adopted a similar template than the ones
above. They're all a bit different in design, but I think they all follow
the same idea/concept, and here's the shocking revelation: *I think it's a
bad idea and I hate them!*

I know it can be useful and helpful, but forcing any of these templates
into every possible help file ends up in a nightmare in some cases. It
might be good for most help files but there'll always be exceptions where
it's just not pertinent at all to stick to the restrictions that were good
for the other cases. Take my word after applying this over 600 times. I can
say I regret it and would like to change it but it's just undoable at this
point.

I'm totally onboard doing a complete rework of Pd's help files and
contributing to the documentation in general. In fact, I've been doing a
lot of that in recent times, by writing new manual sections and rewriting
and fixing many help files. But I wouldn't embrace the idea of choosing a
template for all. I wouldn't work on that and I can go on and on why I
think it's a bad idea, giving many examples why I think this is bad, in
opposition of anyone who thinks this is great and would like to do it
themselves.

The one good thing about these templates is that they do offer a quick
reference guide telling you what are the accepted messages, number of
arguments and things like that. Sometimes you wanna get to this information
very very quickly, immediately, as you're "in the zone" creating a
masterpiece and don't want to interrupt the workflow for any second - but
Pd Vanilla's help files force you to hold your horses for a moment and fish
for that info.

I'm not saying we can't have that when I say the templates are problematic.
I like that too! But I've been thinking of a different solution that
doesn't involve forcing the same window area for every patch and having
that kind of information right in the parent window.

In short, the options are:
- having a subpatch in a standardized way in the same spot of every help
patch called [pd reference] with that info.
- having a html file, available with the Pd application and called from
within the help patch, kinda like [slop~].

By the way, such a separate 'reference' information is sort of what we have
in MAX, totally detached from the help file and its examples. For my work
in Cyclone, I can say I hate MAX's documentation and that it is quite
flawed, but I like this concept!

The easy option is to have this as a subpatch and this can also be done
first as an initial step for the second option (where we can get the
information and put it in a separate html file).

Cheers
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210525/312ea76b/attachment-0001.htm>