Hi devs,
As the title says - can anyone point me to a set of best practices / template / really great example for plugin documentation?
I’m working on a plugin with a few modules, and if there’s a documentation standard I’d like to adhere to it.
There isn’t. Pointing to a dedicated page in your github is an easy way to do it. Here’s a typical one of mine. Sometimes people get fancy and make a nicely formatted PDF, but it’s much more common for a module to have no documentation at all.
I don’t think there’s a link in your reply?
oops! fixed it.
Thanks!
Best practice is to write some. Put it somewhere you can link to from your module and put that url in the plugin.json.
We can at least start there, which is more than many module devs do.
You can check out what other people do.
For my plugins, I make a doc folder in my github repo. I have an index.md for the plugin, and a module.md for each module in the plugin. The index page provides a summary and a listing of the modules with links to their page. Each module page links back to the index. The repo README.md links to the documentation, but otherwise the content in the repo readme is about the repo, the license, building the plugin, and similar dev info. All the plugin docs are in the doc folder.
My examples:
2 Likes
Thanks, and keep 'em coming!
Fortunately or unfortunately, I’m constitutionally unable to put something out in public with no documentation at all… guess that’s a pretty low bar to clear.
1 Like
yes. I also would never release something in public with no docs. But plenty of ppl do.
If you want examples to draw from and infer what makes for good docs, I’ll suggest this thread:
Oh cool, hadn’t seen that thread.
Mind you, that’s just his opinion. But reasonable…
Yeah, if there’s one thing I’m learning by asking this question, it’s that there isn’t an official doc standard.
2 Likes
I was thinking yesterday that in general I will not use a plugin or module that has no manual. That thought was the result of my experiments with a newish plugin in the Library that has no manual or other documentation. There are some YouTube videos but for me, a video cannot replace a manual. I will probably miss some good modules by following this philosophy, but, that’s life;)
2 Likes
Here’s what we did: VCV Rack Modules Manual
Don’t mean to say that’s “the right way”, agree that there’s no single established standard. And also that “have some docs at all” is a thousand miles better than not that. 
But one thing I think we got right, that I also like when others do: If you’re documenting a whole set of modules, make sure the whole thing is easy to navigate! Doesn’t have to be a dedicated site like this, putting it all in a Github readme is fine, but make sure to put a TOC (with sensible quick-jump header links) at the top.
And if relevant, include a section about any functions common to all the modules in your set! Like right-click menu choices or the like.
3 Likes
The other thing we did which is an important t form of documentation is make sure our parameters and ports are labeled, the tooltips have correct units and descriptions, and the type ins work. Also for effects that bypass ports are connected.
To make this easier, if you grab the baconmusic rack package, there’s a module called lint buddy which if you hook up to your module will do a few checks and stuff. It doesn’t have a very good manual though. Chuckle. But I use it whenever I’m writing a module to make sure the in app documentation is there.
4 Likes
it’s much more common for a module to have no documentation at all
While this might be true when considering all the plugins ever released, and fairly inactive, and so on, the degree of documenting modules is actually quite high. It is much more common for an actively developed module to have documentation than no documentation at all. Out of over seventy (70) most recently updated plugins, in the recent four months or so, only four don’t have documentation for their modules.
2 Likes
Checkout the MindMeld documentation which I think is excellent.
However, it still hasn’t been updated to include vertical randomisation for ShapeMaster.
3 Likes
I’m at a similarly early point in plugin/module development mode, and had similar wonderings. Although I’ve deep dive on the subject yet (pinch of salt, etc), I’m so far getting the feeling that Rack and Fundamental are probably the best reference material “if in doubt”.
It’s nice to give builders a root-level README.md explaining how to build and install your plugin, be it make && make install or whatever else.
You can also document the actual code and deploy an HTML site to GitHub Pages using Doxygen, like Rack does, which can include your README.md as a landing page, and can spit out PDF’s as well as all kinds of other formats… but obviously, code function signatures etc are not necessarily of much use or interest to end-users of your modules. You can just add extra custom markdown to the Doxy project if you wish, to make a “normal” manual with a build system.
As a user, I find I rely on good tooltips and labelling a lot. I’m not really adventurous; if a module has a big learning curve and verbose docs, I’ll be less likely willing to try to learn it… there’s so much else in the library already.
I guess my overall feeling is well-considered docs are always welcome, but I prefer modules which are more self-explanatory… requiring lots of docs could be a sign of feature-creep.
YMMV 
Oh yeah, the Surge docs are really good. I don’t think my modules are are going to get their own Omri Cohen video though!
LintBuddy just helped me make some stuff more consistent and get rid of enums I wasn’t using any more… good to get a different view of labels & variables.
2 Likes