[erlang-questions] Documentation build process: user comments, finer-grained pages

[Matt Kangas]

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  
manuals.

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
- free

Example of a site using disqus (not mine! :)
http://www.scripting.com/stories/2008/02/15/iHeartEyetv.html

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  
important.

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.

Cheers,
--Matt

-- 
Matt Kangas
kangas@REDACTED – www.p16blog.com