Whilst in general documentation for the MOD Duo is pretty awesome, the one area where I am struggling is the documentation of each plugin, especially figuring out in any detail what each plugin parameter does.
Even something as simple as SwitchBox2 has an on/off switch which is undocumented and non-obvious (at least to me). I’m guessing that “off” means that the input goes unaltered to both outputs, but I’m not sure.
But for many other plugins, it’s a lot harder to understand exactly how they work.
I agree and disagree at the same time… without clearly understanding what each knob does exactly feels a bit like free-style LEGO building and just trying to figure out what fits together and sounds good. But yeah, this option would still be there if I just decided not to read the documentation.
Perhaps this is something everybody could help a bit: simply by commenting in the respective plugin pages. Just a thought.
I’m a bit of a rookie with effects, and not so good at working at the lower level of most plugins on the Duo. I’m attempting to migrate from Zoom multi-fx pedals (MS-60B, MS-50G) that were pretty easy to dial in with their “1-10” type controls, and I find improved Duo plugin documentation high on my wish-list.
The Duo’s interface and capabilities are truly top notch, however poor or non-existent documentation (both plugin and general) doesn’t benefit things from a “polished and professional” standpoint. This could be a negative among the population of potential users.
On a similar note, I appreciate it when plugins come with several preset configurations. Really helpful when you don’t have a clue at how to manipulate the lower level parameters.
Hahaha, disagreement is just my default reaction towards basically everything. It often disappears when discussing things further
That being said, I agree that the comments are actually not a good place for explanations. It just came to my mind because we users seem to to comment there much anyway.
The wiki.moddevices.com is a much better place for this. Registered users could help there, resulting in only little chance of vandalism. And with a fixed naming scheme and URL for each plugin, it would be simple to have the MOD GUI either pull info directly from the wiki or have a permanent link to it in the web-interface.
This could work OK, but I still think that the cleanest solution is to keep the plugin documentation together in the same repository as the plugin code. That way if a new version of a plugin adds or removes or renames a parameter, or changes its meaning/purpose, the documentation will be automatically updated at the same time to match the code. Then the updated documentation will appear automatically in the MOD Duo UI as soon as the plugin is updated, so it will always correctly reflect the version of the plugin which is currently installed on the MOD Duo. That way there is no need to ignore the incomplete documentation right in front of you and follow a link to a different page to find the useful documentation.
In contrast if the code and the docs are in a different place, it’s far more likely that the docs will not be updated when the code changes. Also if you have a page per plugin in the wiki, then that page will have to document all versions of the plugin, which is hard to do cleanly.
Of course the downside is that it’s a bit trickier to change documentation in a source code repository, especially if it’s not hosted somewhere friendly like GitHub. But I think the extra effort would be worth it in the long run.
Having code and documentation together is awesome, especially in some kind of structured format. Perhaps there is something in the LV2 spec that fills that gap?! BUT when you say:
you implicitly assume that someone would update the documentation as well. And I think this is not going to happen. Otherwise we would have at least some kind of documentation. My conclusion is, it should be as easy as possible for community members to add a few hints here and there.
IMHO the knob functions are quite stable, in fact I have yet to see one added or deleted. Once they pass the @falkTX quality inspection plugins are stable and do not change much. The updates in the store are just so frequent because plugins are updated in groups…
Documentation is something that has long been called for in the open source audio community. Many of these plugins have documentation already, but its wherever the developer put it. Many plugins were written long before MOD was ever heard of. Others have poor or no documentation and the authors aren’t ever going to (many devs hate writing documentation).
There is a forum discussion attached to each plugin (go to pedalboards, then plugins, and select any plugin at the bottom there’s a “start discussion” button or a link to the previous discussion.) A link to the authors plugin docs could go there or a user maintained wiki.
There is a “i” button for information about each plugin in the pedalboard builder and the plugin store. That should link to the documentation I thought (TBH I’ve never clicked it!).
For now I’d suggest you ask specific questions about plugins to force the authors or those who know to write down the information somewhere (forums) and then hopefully the community can distil that down to some useful documentation that can be posted in the appropriate place.
Documentation “all over the place” seems to be the standard… even for my own projects
What would be an appropriate place for you, @ssj71? I still think the wiki would be a good starting point. It has a proper rights management (no vandalism), is accessible from outside the MOD ecosystem and with one of the wiki bots [1] the information can be easily collected and aggregated.
I document my plugins on my website (http://ssj71.github.io/infamousPlugins/plugs.html) and in the readme. I really don’t want to have to maintain another place of it. I’d probably just put a link in a wiki to my site.
I do think a wiki probably makes the most sense. But then I’ve also seen a lot of unmaintained wikis (including the opensourcemusican.com one that I should be maintaining).
Sorry for my cynicism, I just think documentation is something that is hard to pull out of free projects. We should strive for it still.
Documentation is generated from the source-code. Write once, use in various place.
There are various tools to aid the process (help2man being my favorite one). For LV2 plugins I use lv2web to generate HTML doc from lv2info. 2 examples: http://x42.github.io/sisco.lv2/http://x42.github.io/midifilter.lv2/index.html
Ideally however documentation should go upstream and included in the respective plugin description and per port description: If a plugin-port has a comment/description: You can hover the mouse over a control in the user-interface and get help as a tool-tip right there. No need to visit some web-page. Example below:
IMHO a wiki sounds more useful to collect higher level, non-technical information about plugin. Stuff that should not go into a reference manual, like how it sounds, what you use it for and in what combinations. There’s some overlap with sharing pedalboards though.
@x42 Exactly, thank you - I couldn’t agree more! Tooltips on mouse hover is way more helpful than having to click through 2 or 3 links and then scrolling to find the relevant docs for a given parameter.
Full ACK. It’s just… well, I did not mean that the user has to visit the wiki page (although I indeed think that it would be good to have place for collecting and summarizing information nevertheless). My point was, that we, as a community, could grow and nourish a wiki and let the LV2 host or whatever the appropriate level is, pull the text from the wiki page and show it as tool tips. Why? To make it easier to contribute by just writing a few lines instead of looking up for the _n_th time how to make make a pull request and bother @falkTX with it. But sure, docstrings have their own advantages.
I submit pull requests for a living, so I can certainly provide help with that if needed!
I’m full of admiration for @x42’s approach here - I think a single source of truth (i.e. the source repository) is the most efficient and reliable way to go, and lv2web produces great results. I’m not sure what (if any) extra work would be required to produce per-parameter tooltips in the MOD Duo UI, however. @x42, were you saying that this is already implemented and any LV2 plugin which documents plugin-ports automatically gets tooltips, or was that screenshot just a mockup?
You do raise a valid point.
Besides, many guitarists probably think “pull request” is some new fretboard tapping technique
A wiki or forum can certainly help to bridge the gap.
From my own experience I can tell that coming up with concise documentation for a control ports and plugin description is harder and more time-consuming than it seems, particularly for a non-native speaker and dev to whom it’s obvious anyway. Beta-testers and a community certainly helps there, and no it doesn’t have to be a PR or patch.
I also think that no documentation is better than misleading or wrong but authoritative-sounding documentation. The latter is a bit of a problem with wikis.
Does it also pick the localized/translated description? and if not, are the any plans for this down the road?
LV2 comments and descriptions can be translated. The web-browser does send the user’s locale in the HTTP-header, so the GUI could show documentation in the user’s preferred language.
Translations would be another task to lend itself to crowd-sourcing.
