[ruby-core:39452] Re: Comments on HowToReportEnglish

Hello,

2011/9/10 Andrew Grimm <[e-mail]>:
> I've done some proofreading for HowToReportEnglish, and I'd like to
> discuss improving the content.

Good work, and thank you for your comments!

I'm an author of the Japanese draft version of the page.
First of all, I did NOT write the document to put bug reporters under
any obligation.  This is just a guideline to facilitate communication
for bug report and fix.
We should handle all bug reports with respect.  I hate to see a ticket
rejected just because it does not conform the guideline.


> In "Simple Steps", bullet point 1, the patchlevel is different in the
> English version compared to the Japanese version. As well as changing
> the patchlevel for the English version, should there be a link to a
> page stating what is the current stable version?

Agreed.


> In bullet point 4, "Write the things in (1)" doesn't make sense to me.
> I think it means to refer to (2), and broke in
> http://redmine.ruby-lang.org/projects/ruby/wiki/HowToReport/diff/10
> and http://redmine.ruby-lang.org/projects/ruby/wiki/HowToReportJa/diff/36
> . This probably should be fixed in both the English and Japanese
> versions.

Yes.


> According to Google Translate, there's a line in the Japanese version
> talking about "Priority" and "Status" - is it saying they should be
> left alone?

Yes.


> Should "field_mailing_list" be changed to "Preferred language", and
> put at the top of bullet point 4, in both the English and Japanese
> version?

Yes.


> There's some fields I'd like explained, even if it's just to say
> "leave them alone": Assignee, Category, Target version, Start date,
> Due date, Estimated time, % Done. With regards to "Start date, Due
> date, Estimated time, % Done", are they actually used by Ruby
> maintainers? If not, is it practical to remove them from the form?

Strongly agreed.  I've never seen the fields used effectively.

But unfortunately, I heard redmine does not allow us to disable them.


> With regards to the heading "More steps for reporting": is this
> supposed to be instead of, or in addition to, "Simple Steps"? The
> current wording of the title makes it sound like the latter, even
> though the content makes it sound more like the former.

I intended the former.  We are happy enough even if reporters follow
only the simple steps.  We are happier if they follow the "More steps."

The words "Advanced", "More helpful", or "Smarter" would be better.


> In bullet point 2 of "More steps for reporting", there is "Why is this
> problem important?". Aren't all bugs important? Some bugs may affect
> certain uses of Ruby, but not other uses, but does that make a bug
> unimportant?

Would "significant" or "severe" be more suitable?
Yes, all bugs are important, and all bug reports are really helpful.
But release management is also important.  So we'd like information
to decide the priority.

For example, a regression, a segfault, a build failure on supported
platforms, a bug that breaks a famous gem used by many people, and a
bug that cannot be work around, will be considered significant, and
we should address them before release.

Just lack of consistency in API design, a bug in very corner case,
a bit performance degradation, or a report that have no information
about the significance, may be considered unsignificant unless the
bugs affects actual and valid use case.


> In the section "Make better reports", the "Repository guide" linked to
> is slightly outdated. That's probably outside the scope of this
> discussion however.

As written in "More steps", we are happier if reporters check their
report with trunk (though we do not force them to do so).  The link
provides the way to get trunk.  Actually, it seems to need update,
though.


> "Don't use rvm; Prove that it's not rvm's bug." - is this still
> required? Are people still submitting erroneous bug reports as a
> result of problems with RVM?

No, I haven't seen such a report lately.
But I believe that it is important to reduce the cause of a problem.
And this is just a tip; a reporter does not have to follow it.
So I think it is good idea to leave it.


> In the section on general bug-writing advice, what is meant by "Write
> a fact objectively"?

Seems incorrect translation.

I intended (in Japanese) that it is better to write not only "the
current behavior is not intuitive for me!", but also actual case
in an objective perspective.


> "Check List of IRC and ML and join them." - Is ML an abbreviation for
> "Mailing List"?

Yes.  Is the abbrev less common in English?


> If reply templates are going to be listed, can the one saying "May
> Ruby be with you" be mentioned, not just the templates explaining why
> a report has been rejected? Otherwise, it seems a bit negative.

I didn't know them!
This section used to provide information about erroneous bug reports
that are reported frequently.  But currently it is not for reporters,
but for rejecters ;-(  It is too negative.  I *think* they be moved
into another page, such as "HowToReject."


Andrew, thank you again for your contribution and comments.

-- 
Yusuke Endoh <[e-mail]>