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

[t ty]

Perhaps have the docs linked under wikibooks
(http://en.wikibooks.org/wiki/Erlang_Programming). Example:

Within wikibooks have

Module: erlang
Function: is_list/1  (link back into erlang.org document that has the
official description)
Summary:
Usage:
Comments:


Regards

t

On Feb 16, 2008 3:39 AM, Matt Kangas <kangas@REDACTED> wrote:
> 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
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://www.erlang.org/mailman/listinfo/erlang-questions
>