Hi Jesse, brace yourself, for I’m going to criticize the google-doc proposal for I am concerned that some may perceive it as being LV2 cannon.
I do value your time for coming up with the proposal. I do agree that plugins should have good documentation, ideally included with the plugin, but I do disagree with nearly all the points on how the description/doc should be formatted.
- The title: Plug in name without developer, abbreviations or codified terms. (ex. Gx, Rkr)
It makes no sense to add that to the description, does it?
The plugin already has a name, title and author in semantic RDF, properly formatted. There’s no need to add it again.
- Name of the plug in without developer, and direct mention to eventual inspiration models.
- A catchy and impactful short sentence about this model. (only if deserved)
Why only if deserved ?
A tagline or single sentence can be handy. Then again, ideally the name speaks for itself. So “only if appropriate” (not deserved).
- Historical context, legends who used it, main ways of use. (If applies)
Frankly, nobody cares nor should care about historical context when you want to use a plugin.
I also expect this will only lead to false assertions and bias. A user may believe a plugin emulates something while in fact it does not even come close. If the plugin emulates vintage gear it may or may not be mentioned in (5) below.
Furthermore you imply that a single effect can be responsible for the style and sound of [some legend], which is only rarely the case, if at all.
- What it does, strongest characteristics or usages. This is where we must make the greatest efforts in ensuring easy understanding.
Why only “strongest”? IMHO a description should be more like a reference manual and outline all general uses. Specific usage variants can be done with presets (which can also have a description).
- Important considerations such as controls added to the original inspiration or eventual significant modifications (If applies).
- Controls: If not self-explanatory, we should provide quick and simple instructions of what each button does and why using it.
Nope. controls should be documented themselves (the MOD already shows port-annotations in tooltips)
- Features: developer, inspiration model, version etc.
Features should already be mentioned in (5) above, no? Version is already present in the plugin’s RDF.
- Legal: all the legal disclaimers necessary.
There is already a special semantic license field in the RDF for that. Trademarked names in the description can be tagged with ®, ™ as needed.
I highly recommend to focus on 1. write once, 2. don’t repeat yourself.
Also keep in mind that there are other LV2 hosts using the description.
Also all the examples you provide are rather unprofessional (“messing with the gain parameter”) and read like marketing BS (“capture the sound of an era”) to me.