[LAD] LV2 code examples and documentation [was: Re: State of Plugin API's]

[David Robillard]

On Mon, 2009-11-02 at 19:37 +1100, Patrick Shirkey wrote:
> Hi,
> 
> I'm just having a quick browse of the http://lv2plug.in site now and 
> while at first glance it looks like it has everything in place, after 
> looking into the system a little more deeply there is a definite slant 
> towards documentation that is more advanced than the average n00b 
> developer would be ready to absorb on first attempt.
> 
> There are two docs that give plenty of useful info for starters but they 
> are assuming a certain level of expertise. Also the doc for "complete 
> idiots" comes across as more than a little patronising. I can't tell if 
> that was the intention of the writer or not.

Bah.  Do we even want people around with such a large stick up their ass
as to take this seriously? :)  The Dummies books are one of the best
selling book series ever.

> I can see a gap for a *very* simple "hello world" document. It will very 
> quickly outline the exact steps required to build the most simple plugin 
> possible. Maybe if we are lucky our resident writers Dave Phillips or 
> Daniel James will have time to edit it for clarity before it is posted.  
> I will work on the draft for this using the two pages above as reference.

An overly well documentated example/stub plugin would be best for this,
IMO, since it doubles as an example they can modify to make a real
working plugin.  Don't get too caught up in the importance of external
documentation - people generally only read it as a last resort.  People
are far, far more inclined to work from examples - combining the two is
the best of both worlds.

The bundle can also have a makefile (or whatever) to generate
documentation and such, with the side-effect that people who base their
plugins off of that bundle automatically Get It Right.

> On the page for loading plugins it should have an accompanying set of 
> example code packages for c, c++, objective c++ python, java, c#, vb... 
> If anyone would like to submit a code example for one of these languages 
> that would be very helpful. Ideally it will be less than 100 lines of 
> code and hopefully significantly less.

There are too many variables in implementing a host to do this, to be
honest, and explaining how to do it without a library will probably
scare people away more than anything (you need to query an RDF document,
for starters...).

This is why slv2 exists.  I don't pitch it as "necessary" or
"standard" (it isn't) since I wrote it, but I don't think every host
reimplementing e.g. plugin discovery is a very good idea at all - it's
likely they'll get it wrong.  That kind of stuff should, without a
doubt, be implemented in a library.  This way everything works
consistently, the same environment variables are obeyed, the same
plugins are discovered, etc.  I doubt there are people capable of
writing a host for whom http://drobilla.net/docs/slv2/ (or the
equivalent man pages) isn't enough information to get off the ground.

Focus for this kind of thing should definitely be mostly at potential
plugin authors, IMO.  There are far fewer (potential) hosts, and they're
more complicated, and typically headed by someone who knows what they're
doing anyway.  Documentation efforts should be focused at the casual
weekend developer type who might actually come along and read the docs,
determine it's easy, and write a plugin or two.  They're not so likely
to write a DAW :)

-dr