[erlang-questions] Documentation build process: user comments, finer-grained pages
Sat Feb 16 09:39:38 CET 2008
On Feb 15, 2008, at 7:41 AM, Matthias Lang wrote:
> Looking at the "user comments" on the PHP site pretty much put me off
> any ideas about having "user comments". What a collection of flotsam
> and jetsam!
For a moment, let's talk about blogs, rather than online software
Many bloggers have strong feelings about allowing comments on their
posts. They're either against it, or think it's an essential part of
the medium. Often you can predict who will be on which side of the
issue. Established authors don't like the "hassle" and "messiness" of
comments. Authors who were weaned on blogging often see blogs as a
"conversational" medium; without comments, there can be no conversation.
Spammy comments is a big concern for top bloggers. Of course, quality
of legitimate comments varies too. Solution? Better tools. :)
One popular solution for top tech blogs (in USA, at least) is http://disqus.com/
- strong spam protection
- threaded comments
- ranking of comments up/down via "vote up/down" buttons
Example of a site using disqus (not mine! :)
As for Erlang's online manual... I agree with Dimitri that the
comments in software manuals (ala php.net) are more useful to newbies
than for old masters. It's the newbies who need multiple perspectives
on the same topic; they don't see how everything fits together. By
permitting comments, you let users fill in the gaps they think are
Or, as someone much wiser than I has said, "With enough eyeballs, all
bugs are shallow". :)
Re: "flotsam", disqus-style ranking helps bubble the "best" comments
(as voted by readers) to the top. PHP.net's docs lack this, but I
think it's important.
To do comments right, the Erlang docs would also need to be chopped
into more distinct URLs. Comments at the bottom of a long page like http://erlang.org/doc/man/io.html
make little sense. You want comments to be at the function level too.
PS: Chopping into smaller pages benefits SEO. A URL like http://doc.erlang.org/io/format
(with a matching title) will be ranked higher by Google for the
query "erlang io:format" than its current counterpart.
More information about the erlang-questions