P16: a blog by Matt Kangas home archive
07 Feb 2008

User-added comments in the Erlang documentation?

Here's a second idea for improving the Erlang documentation, stemming again from a comparison to PHP.

How about supporting user-added comments in the documentation?

I'm talking about the little "add a note" button at the end of every page of the PHP manual, and the stream of user-contributed "notes" that follows. Or as a friend suggested, look at PostgreSQL: their online manual is available with and without comments.

Allowing comments is just as necessary for online technical manuals as for blogs. It's all about putting Linus's Law into practice: "given enough eyeballs, all bugs are shallow".

Personally, I've spent a lot of time reading the PHP manual in the last 4 years. Even though the quality of the user-added notes varies greatly, I've always found the note-sections helpful, because I never read them unless my question isn't answered by the preceding manual page.

You can think of inline notes as a way to accumulate FAQs (and answers) wherever they're needed within the official manual.

My suggestion for implementing: don't bother to build a comment-handling framework, just borrow some existing framework. Not sure about PostgreSQL, but PHP has a documentation HOWTO. Docbook XML is their core format.

What's Erlang's core doc format? Could we just convert and pour Erlang docs into the PHP doc framework? It looks like DocBuilder is how the HTML docs are generated... will have to dig into this later. :)