[LV2] LV2 Plugin Documentation

[Mark D. McCurry]

Hello LV2 community,

A few days back a thread appeared talking about the current state of the
docs for host developers.
While writing that sketch I did spend some time looking back at the lv2
book (http://lv2plug.in/book) which while it is stated that it is a work
in progress it is the first recommended point to start for people
interested in making LV2 plugins.
I've rambled about this years back, but I'll ramble here since perhaps
that might get others interested in improving the situation.

\begin{ramble}

I think the "Programming LV2 Plugins" book is BAD for beginners to the
point that it likely repels a significant number of people who might
otherwise be interested in building a LV2 plugin.

Why do I think it's bad?

- It introduces the turtle files before getting to a line of code
  Turtle from a new dev's perspective is *weird*. No one else is using
  commonly using it. It does present interesting options, but a new dev
  needs to be eased into it.
- No diagrams. People seeing just a wall of text will have their eyes
  glaze over
- It introduces complex cases out of order:
  - providing translation examples before the dev even knows what the
    particular property is really doing
  - Getting into scalePoints on the first (as basic as you can get)
    plugin??
  - Talking about threading information on each callback for the first
    plugin?
  - You need to motivate these situations before introducing them to the
    dev
- Valuable asides about LV2 e.g. the motivation of turtle file use being
  inline with the rest of the text. Literally putting a box around this
  information to mark it as useful, but not directly part of the example
  would be enough
- Spending too much time on stub functions

My stance is that a lot of this is a direct consequence of generating
docs directly from source files in a literate programming manner.
The way that code should be explored and explained is in many cases
non-linear and will jump around introducing new concepts, then code or
showing a motivating case in code, then talking about the concept, and
more code.
This sort of discussion is natural when writing a document, but really
awkward when entering it into a linear source file.
Don't get me wrong, I like the idea of literate programming, I just
don't think that it works in this case.

I've tried to go through the lv2 book as written several times and
stopped reading because it made LV2 look complex.
Making things look more complex than they actually are is a great way to
repel possible users/devs/contributors/etc.

So, what should be done about these complaints?

- Each example should state clearly the goals of which LV2 concepts they
  will introduce and how they relate to each other
- Code should be at the forefront when possible.
  Motivating examples should be used to show the user how extra features
  *help* them accomplish their goals
- Code examples should be simple
- Detailed information should be blocked off using Admonition blocks
  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#admon-bl
- Low importance code should not be repeated in a way that eats up
  vertical document space.
- Block diagrams should be used to provide at a glance views for each
  stage
- Timing diagrams should be used to help retain attention while
  reinforcing comment
- There should be a boatload of links to the LV2 specification when
  possible (this may require improving the linked specification docs as
  well)
- When LV2 has a _weird_ feature, this document should be able to sell
  the reader on why it is a better solution than other options (use
  admonition blocks for longer form descriptions)
- Keep things informal and give the document a sense of personality
  (making music is supposed to be fun after all)


What might this look like?

http://fundamental-code.com/tmp/lv2book.html is my (very very rough)
stab at shifting the organization, complexity, and tone.

Will this effort go anywhere?

I don't know, but it's been one of those ideas floating around in the
back of my head for a few years now.

LV2 does some cool stuff, but when outsiders look at it, LV2 looks
*complex*.
This complexity looks unnecessary, strange, and hard to program with.
I know that a lot of people put a lot of thought into what was wrong
with prior plugin standards to help spawn LV2 (heck, just look at all
the debates in the early years of the LAD mailing list).

That's why it drives me a bit nuts that people take a look at the docs
and don't see all the cool stuff and how it should be great.

\end{ramble}

--Mark
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 455 bytes
Desc: not available
URL: <http://lists.lv2plug.in/pipermail/devel-lv2plug.in/attachments/20180520/a2d9c89e/attachment.sig>