[oe] Documentation problems

[Frans Meulenbroeks]

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

That is somewhat the advantage of a wiki. You can contribute to the best of
your abilities and others can extend with their knowledge, expertise and
language skills.
Then again, I understand that there is a risk that faulty information is
created (as was also expressed by Koen). However I cannot really recall big
such problems with our wiki.

There is of course another problem (which does surface every once in a
while). Sometimes people write pieces based upon outdated information. And
even if not, the information itself will become outdated.
E.g. if we deprecate PR (which is a good idea btw) this needs to be changed
in the wiki too. That is a part of the process that is not really well
developed.
outdated information is equally wrong as other faulty information.

As stated before, for most people writing documentation is not particularly
fun, so it should be made easy with few annoyances. Make it hard and you
will hardly get contributions. Turn people down a few times and they are
gone.

>
>
> >
> > (note that I am not a native english speaker so this is not too unlikely;
>
> neither am I.
>
> > also if there are language errors in a contributed piece of documentation
> > on a wiki other people more proficient in english could correct those
> > easier and better than I ever can),
>
> right now there is no review process for wiki. So if I write a
> document it does not get notified
> to people and chances of someone really stumbling into this new piece
> are new users who are studying
> that document and I think reviewing it beforehand is a good thing
> since I might have written it wrong
> besides grammar errors. I think wrong documentation is worse than no
> documentation.
>

I agree with the wrong documentation is worse than no documentation.
I'm not sure whether there are no wiki plugins to allow notification.
(and it is always possible to examine the recent changes page, but that is
not really convenient).

BTW it is always possible to lock certain pages and only allow a limited
set of users to edit those pages. I can imagine this is done wth the pages
that are considered core.

Frans