Suggestion for changing README.md

[gregdl]

I'd like to suggest changing the wording of the readme.md file here in one particular area:

• avoid redundancy: check if there is already another act that does (exactly) what yours does.
  if yes, see if you can extend an existing act before creating a new one. check back with the original authors / the developer team > first.
• quality over quantity :)

Frankly, I'm not sure what the purpose of this is for users and potential contributors. My reading of this is that it is potentially uninviting or discouraging of new contributions and improvements to ppooll. Given this repo is the "core" ppooll and pull requests are controlled by the developer team then there is already a filter of sorts. So what exactly is the purpose of this kind of message?

• There are quite a few acts already in the core package that have overlapping feature sets.
• Extending existing acts can be difficult given the lack of documentation of some acts.
• "quality over quantity" seems to go against the spirit of development and innovation, and seems to imply that the core acts represent some kind of gold standard.

[jpsteccato]

I hear you on the redundancy of the some the acts in the main "ppooll" repo-- there are also several acts (like the jit acts, other "abandoned" acts) that should just be moved to a separate repository (maybe community?).

Maybe the wording needs some tweaking, but I do stand by the sentiments expressed regarding redundancy and quality. There are standards in terms of how acts should be created, and while there is a lot of nuance to all the "ll" abstractions and patching conventions of ppooll, I think it is possible to boil these down into a comprehensive doc that can be used by anyone to make an act.

IMO, the main "ppooll" repository should be as lean as possible. I understand why this may feel "exclusive", but it's only for the sake of maintaining a solid, stable foundation. Contributors will come and go, and nobody wants to maintain someone else's patches (esp if they don't use them or know how they work...).

Community Contributions was created as the destination for user contributions, but I'm beginning to think that even that repo will be too much to maintain. I really like that knfld recently released their own repo of acts. This seems like a more viable solution for sharing and maintaining acts, as the authorship and maintainers can be held responsible for updates/bug fixes.

The community around ppooll has grown significantly in the last couple of years, and in response, we need to find a sustainable system that works for everyone. If I'm sounding out of line on any of this, feel free to let me know, but please keep in mind that we are just trying to find a way to support this user base while preventing burnout or feeling overwhelmed :)

[gregdl]

Thanks for the response, I appreciate it. I agree the main repository should be lean to make development easier to maintain (and reduce friction / points of failure with new users etc). It sounds like maybe the intent of this part of the readme is to explain how user contributed acts can be integrated into the main ppooll repository, and provides very useful information on what is expected of acts in the core repository (e.g. help files, etc).

However, the title "todo before creating a ppooll act:" is maybe what contributes to this discouraging impression that sparked my comment. It gives the sense of "before you create a ppooll act do this." But frankly I think people should be encouraged to learn new skills or build on existing ones to create and adapt acts and why do you care if I make another looper or granular or distortion act? Maybe my irritation is just me, but I think communication on the core repository should be done with care.

It sounds like perhaps the text here is for people developing/maintaining acts in the core repository, in which case I suggest the following changes? Just a start / initial idea

Suggestion for readme:

making new acts

• we encourage people to adapt, remix, and create new ppooll acts. ppooll is a great way to connect max patches together.
• there are some useful information in the ppooll help file (click "ppooll" in ho_st act), see "programming support: actmaking_tutorial_" or here.
• there are also useful videos about act making here and here [link to YT videos].
• there is an #act_making channel on the community discord to chat with other people making and learning how to make ppooll acts.
• if you make new acts please feel free to share them! you can do this by:
• • sharing a link to your GitHub repository [what's easiest way? <-- pull request on the readme.md or leave link in discussion board on GitHub?]
• • sharing your act in the #act_share channel of the community discord

developer guidelines

• the following is for people working on maintaining core acts.
• if you would like your act to be included in the core act database please follow the guidelines below and then contact the developers here on GitHub [[a suggestion, or email etc]].
• we try to keep the core act database lean, focused, without too much duplication of function, and with a minimum of external packages to keep development as easy as possible.

ppooll styleguide

[same]

todo before committing a ppooll act

[same]

[jpsteccato]

Ahh yes, I see why this is confusing now. The language there is really geared towards users who want to submit an act to be included in the main ppooll repository-- this should be under a separate header, as you've very nicely separated and worded above :)

@klausfilip @chausch , what do you think?