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

t ty tty.erlang@REDACTED
Sat Feb 16 14:43:27 CET 2008

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)



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

More information about the erlang-questions mailing list