[oe] Documentation problems

[Tom Rini]

On Tue, Nov 29, 2011 at 2:46 PM, Frans Meulenbroeks
<fransmeulenbroeks at gmail.com> wrote:
> 2011/11/29 Khem Raj <raj.khem at gmail.com>
>
>> Hi Frans,
>>
>
> Hi Khem, all
>
>>
>> On Tue, Nov 29, 2011 at 12:24 AM, Frans Meulenbroeks
>> <fransmeulenbroeks at gmail.com> wrote:
>> >
>> > Of course I also do not want to write faulty documentation; then again I
>> > also hate wasting my time, so I think I wouldn't even start if there was
>> a
>> > chance that my contribution might be rejected because the pull master
>> does
>> > not like my style or feels there are grammar errors or so.
>>
>> I consider someone reviewing my patches a good thing. I think it makes
>> me learn things
>> if there is feedback on the patches, I include the feedback and
>> resubmit the patch and thereby improve it
>>
>
> Oh, I consider reviewing patches a good thing too. For documentation it
> also depends on the process and the kind of comments.
> If the person pulling the changes rejects them because (s)he finds the
> grammar not ok and the review comment is "improve grammar", that is fairly
> demotivating (if I knew how to do so, I would have done that upfront).

This would be just as bad as reviewing a patch and saying only "fix
the things that are wrong".  Both are equally unacceptable, and
frankly at this point in the projects life, equally unlikely.

> A few of such rejects will make that most people loose the interest in
> submitting documentation quite quickly.
> And if you have to give detailed review comments or instructions reviewing
> becomes quite time consuming (actually more time consuming than actually
> making the change yourself)

Which probably means the commenter knows enough that they should have
made the documentation change to start with.  This is the price to pay
for not doing the edits directly.  Personally, I've been willing to
pay that cost and explaining it to someone else helps make sure I
really understand it and that the code is also really correct.

-- 
Tom