Re: Commenting Manpages

[Justin Erenkrantz <je...@apache.org>]

[ Moving to docs@httpd ]

--On Tuesday, January 28, 2003 8:10 AM -0800 Ian Holsman 
<Ia...@cnet.com> wrote:

> has anyone considering doing something similiar to the comment
> system that php does with their man pages?

Rich brought this point up on the community@ list when we discussed 
the merits of a wiki.  Rather than put words into Rich's mouth, I'll 
shut up and let him speak.  (Or, let others have a chance to comment.)

But, this discussion definitely belongs on docs@httpd...  -- justin

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: Commenting Manpages

[Joshua Slive <jo...@slive.ca>]

On Tue, 28 Jan 2003, Rich Bowen wrote:

> Well, basically what I said was thus. I find that on the PHP
> documentation web site, on each page, you have a small amount of good
> documentation, and then a boatload of comments, some of which are good,
> most of which are not. Such as system can only be useful if the comments
> are regularly integrated into the docs (if they are good) or purged (if
> they are crap). And of course this would require that someone check the
> entire site for comments on a regular basis.

Or we could have a voting system where users could vote on the value of
comments.  And then a meta-moderation system for users to vote on the
value of votes.  Oh, why don't we just convert the site in slashdot.

Seriously though, another barrier to any fancy stuff like this is our
desire to keep static web pages.  If we were willing to go dynamic, much
more would be possible.  (I'm not saying we *should* go dynamic, I'm just
saying it is a barrier.)

Joshua.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: Commenting Manpages

[Rich Bowen <rb...@rcbowen.com>]

On Tue, 28 Jan 2003, Justin Erenkrantz wrote:

> [ Moving to docs@httpd ]
>
> --On Tuesday, January 28, 2003 8:10 AM -0800 Ian Holsman
> <Ia...@cnet.com> wrote:
>
> > has anyone considering doing something similiar to the comment
> > system that php does with their man pages?
>
> Rich brought this point up on the community@ list when we discussed
> the merits of a wiki.  Rather than put words into Rich's mouth, I'll
> shut up and let him speak.  (Or, let others have a chance to comment.)

Well, basically what I said was thus. I find that on the PHP
documentation web site, on each page, you have a small amount of good
documentation, and then a boatload of comments, some of which are good,
most of which are not. Such as system can only be useful if the comments
are regularly integrated into the docs (if they are good) or purged (if
they are crap). And of course this would require that someone check the
entire site for comments on a regular basis. Not that this can't be
done, but I find that the mailing list is a much more efficient way for
us to do this - at least it works well for us. I'd be glad to have a
comments email address on every page of the docs, with, perhaps, some
way to identify which page the comment was in reference to
(docscomments+mod_autoindex@httpd.apache.org or something).

All, of course, just MHO, and my observation of how this works for the
PHP docs. I know some people like this - I find it makes the PHP docs
almost completely unreadable.

-- 
Nothing is perfekt. Certainly not me.
Success to failure. Just a matter of degrees.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org