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

[Andy Farnell]

The option I feel safest with is (3). Why do I mention safety? I'm not 
saying there is anything wrong with Flossmanuals - *really, but in the 
last few years, as my focus has shifted to cybersecurity and digital rights. 
I've become dismayed with governance issues in free software, from the 
Microsoft takeover of Github to last week's exodus from Freenode... it's 
genuinely a hostile landscape. Diversity obviously does make extra work, 
but it brings resilience. Having only one "official" document is nice but
 not necessary, so long as there's broad accord and a will to clean up 
outdated and misleading materials (one reason I nuked the old obiwannabe
Pd junk pile, the best of which had been ported into Flossmanuals. I found
the community was actually better at maintaining my patches than I was). 
Obviously documentation is not as important as the codebase itself, but 
still a significant asset to lose to a BigTech attack.

* As far as I can see the Dutch non-profit headed by Adam Hyde is exemplary, 
but unless an org literally has anti-takeover measures legally hard-coded 
into its articles of incorporation (or whatever that means under Nederlands 
non-profit law), there's a gap in the wall. 

Perhaps that falls under "other thoughts?", and sorry of it adds noise.

keep well all,
Andy


On Sun, May 30, 2021 at 05:19:35PM -0300, Alexandre Torres Porres wrote:
> 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

> _______________________________________________
> Pd-list at lists.iem.at mailing list
> UNSUBSCRIBE and account-management -> https://lists.puredata.info/listinfo/pd-list

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: Digital signature
URL: <http://lists.puredata.info/pipermail/pd-list/attachments/20210531/e7130097/attachment.sig>