[oe] Documentation problems

[Frans Meulenbroeks]

2011/11/30 Tom Rini <tom.rini at gmail.com>

> 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.
>

Hm. I'm not too sure about this. With a patch it is much easier to
distinguish between right and wrong.
With explanatory text the scale is much wider, and for text I suggest to
look at the content (which obviously should be technically ok) and perhaps
a little bit less at style and grammar (but of course it should remain
understandable).


>
> > 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
>

I'm not sure about this. It could well be that a reviewer comments on style
and structure, even though (s)he cannot judge the technical details (and
therefore probably could not write the piece himself).
And I feel we have some people that seem to like it to pick on other people
not following the guidelines they are not willing to document.


> 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.
>

Sure. I understand and appreciate that.
Then again for code sometimes the feedback that is given with rejected
patches is neither helpful nor stimulating.
If that happens with documentation too, soon someone will end up whining
that no one wants to contribute to the documentation.

My two cents.
Frans.