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

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.

At 18:33 08/11/24, Florian Gilcher wrote:
>Hi,
>
>as some of you might have noticed, Wolfgang N疆asi-Donner and I had a  
>look into the new Fiber feature of Ruby 1.9. Aside from the bugs[1] it  
>is also evident that the documentation for Fibers is severely lacking  
>(as in: non-existant). We have a hard time finding actual  
>documentation and reasons for most things concerning Fibers. That  
>leads to the general question: Should missing, incomplete or erroneous  
>documentation be considered and filed as a bug more aggressively?
>
>There is a bug-category DOC, but it doesn't seem to be used very  
>often. [2]
>
>There are several reasons to make this a good move:
>
>* The obvious quality improvement.
>* Documentation is a good start for people that want to get involved  
>and have a look around the interpreter.
>* Documentation tasks can be picked up by people that are not the  
>implementors.
>* Easier to keep track of the dark corners.
>
>Reasons against might be:
>* Could be considered as noise from developers/ticket-managers -  
>especially when a feature is new in trunk.
>
>On a side-note, it might be nice to have a wikipage regarding the  
>policies on how to report bugs. Thats why I am asking: I am totally  
>unsure whether I step on someones feet when I start to file bugs in  
>that category.
>
>Regards,
>Florian Gilcher
>
>P.S.: On a second side-note: on the assumption that a most visitors of  
>the redmine-site don't speak japanese, it might be nice to explicitly  
>state on the frontpage that the wiki is bilingual. I know that some  
>people at my office were irritated by this.
>
>[1]: In one case (Fibers don't call initialize) we don't know whether  
>it is a bug, because the behaviour is non-standard and undocumented -  
>but could be intended.
>[2]: The category has a total of 3 tickets.


#-#-#  Martin J. Du"rst, Assoc. Professor, Aoyama Gakuin University
#-#-#  http://www.sw.it.aoyama.ac.jp       mailto:[e-mail]