[ruby-core:20084] Re: Is missing documentation considered a bug?

Hi Martin,

that may be a good stance, when we are talking about small things, like:
#constants now returns symbols instead of strings, but no one documented
it.
But especially on the case of Fibers: i don't have enough insight to  
write
more than a rough introduction out of stuff other people wrote as  
tutorials.
Heck, even figuring out why you have to use require 'fiber' to use  
Fiber#alive?
took me more time than I wanted to invest. There are more places like  
this.
I don't feel qualified and also don't want to have the hassle of running
through the mailing-list every iteration. I also cannot comment on the
runtime behaviour of fibers, because the only source-code comment
about them is (Quote):

/***********/
/* Fibers   */
/***********/

On a sidenote: fibers.c doesn't hint at the fact that the  
implementation is actually in
cont.c -> frustrating.

But i'm not talking about how to handle patches, it is much more a  
question of
attitude towards documentation, thats why I am starting this  
discussion. The maybe
it's more my need for discussion that the actual incident ;).

Consequently handling documentation over tickets (maybe bug is the  
wrong word)
has multiple advantages:

* There is a track record of whats done, whats being worked one and what
needs to be done. To stress the fibers example again: writing a good  
doc for
it is not a 1 hour task.
* You can review changes in a web interface.
* It gives implementers the ability to assign the documentation of  
their library to
someone else - which automatically leads to some kind of code review.  
That
might also be good for coders that struggle with wording what they do.
* On the same wave, it allows implementers to commit a new feature and  
write
the flag the documentation as 'to be done by anyone with time'.
* Statistics can be used for motivation ("Hey, people, wanna get  
involved? We
have XYZ open documentation tickets, just grab one, be a contributor.")

This all does not mean that I shy away from the work and want to file a
ticket just for others to handle it. But sometimes I just come across  
something
I don't really feel especially competent or motivated - so my  
contribution
would be a spotlight for someone else.

Let's face it: Documentation is Rubys mistreated stepchild and the  
fact that
the only answer to my question is "if you are not okay with it, write a
patch" kind of shows that this will hold true for some while. Currently,
it is handled on a "if someone does it, it's nice"-basis.

Regards,
Florian Gilcher

P.S.: Btw., I know some projects (granted, mostly internal) where  
missing
documentation has the status of a blocking bug. A good thing, in my  
opinion.

On Nov 25, 2008, at 2:21 AM, Martin Duerst wrote:

> Hello Florian,
>
> This is a purely personal opinion, but my suggestion is that
> the best thing you can do is provide patches (i.e. parts
> of the missing documentation). If there's something you can't
> figure out, just leave it out or ask a question in your issue.
> If there's something that looks like a bug (e.g. the "Fibers don't
> call initialize" below), file a bug report (on the functionality,
> not the documentation), and it should be either be acted upon or
> rejected, which will give you an answer.
>
> Regards,     Martin.