[PD] Pd FLOSS Manual, what to do with it?

[Alexandre Torres Porres]

btw, anyone knows who still has access to edit/maintain Pd's FLOSS Manual?

Em dom., 30 de mai. de 2021 às 17:19, Alexandre Torres Porres <
porres at gmail.com> escreveu:

> Folks, we're on a roll debating all things related to Pd documentation
> here and there and I'm now focusing on the Pd FLOSS Manuals issue.
>
> Pd has this very famous and long lasting FLOSS Manual. It's old and it
> tells you how to instal Pd Extended 0.39! So, it's from the extended era
> and still references to 'extended objects'. For what I see, it was a Manual
> that came to be in the Extended era as a Manual to it. Back in the day we
> basically all used just Extended anyway and were mostly oblivious to
> Pd Vanilla and its manual.
>
> And by Pd's manual, I mean http://msp.ucsd.edu/Pd_documentation/index.htm
> - I know that's called 'Pd Documentation', and that it is confusing, cause
> it actually is an 'html Manual' and it refers to itself as "this html
> manual". Anyway, this is also something I brought up on github and is not
> the issue here..
>
> The point is that there's a conflict and I guess this made sense then, but
> it's a problem nowadays. A documentation noise problem. Lots of people seem
> to get to it and consider it "the manual for Pd". We're still struggling
> with a post Pd Extended issue and what was consolidated in its era but now
> sits as ruins. Actually, Pd Vanilla's manual also refers to FLOSS Manuals.
> But these days we have something weird, which is simply the fact that Pure
> Data has these two manuals. One is the official one, included as part of Pd
> Vanilla and its documentation, and this other one, which is terribly
> outdated and actually refers to this unsupported and abandoned fork of Pd.
>
> But the point is, one software cannot have two concurring Manuals, even if
> both are up to date - that'd be silly. The point of FLOSS is to provide the
> one and only official and single Manual for a piece of software. See the
> problem? Csound uses FLOSS Manuals as a place to provide its official
> manual. It's clearly linked in csound.com. Csound also has the
> 'Canonical Csound reference manual', which is actually something else and
> not to be confused with "The" manual they provide in FLOSS.
>
> So, my point is we have to get rid of one of them and have a single
> official one.
>
> Should we then remove the included and official manual from Pd and 'move
> it' to FLOSS and completely overhaul that online version?
>
> Or just get rid of the FLOSS version? Well, that is there, and people know
> it. Burn it down, purge and disappear with it would be bad.
>
> Well, I don't know, so I'm asking...
>
> Another scenario is that FLOSS can still be around, of course, but as a
> museum piece, for those interested in web archeology, as extended is now an
> archeological piece of software. No one touches it, it stays there, but we
> try to make it clear how that is an old, outdated, unofficial and that Pd
> has its own 'real manual. This would help a lot. Or... also, treat it for
> what it is, a manual reference for Pd Extended, not Vanilla, and make it
> clear how Pd Extended is abandoned and so is this manual.
>
> Other than these, the only option I see is we maintain and update these
> two manuals somehow. And I already said how I think that's pointless. I
> also don't know who'd do that... but maybe there'd be a way to manage them
> as two clearly distinct guides. One would be the 'Canonical Vanilla Manual'
> and the other could be 'The Pure Data Manual' (or some other name)? The
> question would be, why to do that? What is the advantage in keeping another
> FLOSS version around?
>
> The thing I can think people like about the FLOSS version is:
> - A) A friendlier look for beginners;
> - B) A nice beginner level tutorial;
> - C) Support for many externals, external libraries, how to use Arduino
> and stuff (more as a tutorial than a 'manual');
>
> These can all be compensated. With 'A)', we can try and make the Pd manual
> look nicer maybe? As for the rest, what really seems to be the substance of
> this is the fact that it serves as a tutorial.
>
> Well, a tutorial is not necessarily a "Manual".
>
> We can add tutorials to Vanilla too... actually, even though it's based on
> Extended, many of the examples there are 'vanilla', so they can be
> easily ported and shipped as part of Vanilla!
>
> As for tutorials that use externals. Well, they would really benefit from
> an update. But a tutorial is a tutorial, this could live somewhere else.
>
> By the way, tutorials can easily be uploaded to deken and be available
> from there. You'd have a tutorial that relies on externals, but that's ok
> too (my live electronics tutorial comes as part of the ELSE download)...
> just give instructions in the tutorial on how to install the needed
> libraries from deken as well...
>
> But if the case is made that we should really keep FLOSS and update it.
> Well, maybe we could manage and do that, taking care on how to not overlap
> even know I don't know who'd do it, but it'd mean completely rewrite from
> scratch and get rid of some of the stuff. That's bad too, as the old
> version would be lost (so have it sit as an 'old extended manual'?).
>
> So, in short, possible scenarios include:
> 1) Forget about floss, tell it's outdated (rename it to pd extended manual
> maybe), focus on Vanilla's manual. Bring stuff we miss and like from FLOSS
> to current Pd in some new form.
> 2) 'Move' Pd's manual to a new FLOSS incarnation
> 3) Keep and manage two versions
>
> My thoughts on these are here, and I think the best scenario is number "1)"
>
> Any other thoughts?
>
> Cheers
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210530/6d2d6d33/attachment-0001.htm>