[QGIS-Developer] Proposal for QGIS Documentation

[matteo]

Hi Alexandre,

thanks for the inputs.. :)

> I agree that we have a long time issue with Documentation. To me, it can
> only be solved with someone working on it "full-time", Which seems to be
> the case if Larissa starts working on it.

+0. We already have many many commits and PR each day since a lot of
time. Of course people are interested/involved in different topics and
anyone contributes in the way he/she thinks is better. Therefore, review
is of course not the most interesting part... (at least I prefer to
write new doc from scratch than reviewing)

> On the other hand, we have the review part, which is something that even
> fewer people participate (me included), and it takes forever...

+10000

We had PR stacked fro months and as I said, merging clean PR (clean =
not breaking anything) is better: also new people can fix errors and/or
improve the docs with the Fix me button without dealing with
git/sphinx/compilation and so on..

> I am not very enthusiast of the automatic merging and closing of PRs.
> People have different velocities, and I don't think it's good to close a
> someones PR (that put some good work on it) just because no one with
> merge rights was able to review it. It is very discouraging.

I'm not happy too. But IMHO is worst to have PR with hundreds of
comments or PR left there for months. This could be also very
discouraging (not only for new people making the first step into the
project).

> On the other hand, if the person has commit rights, then technically he
> can merge it himself , when he feels the work is ready (assuming that,
> like Matteo said it's not breaking anything), without the need for a
> bot. I still think that a review would be is required... Just like it
> happens in the Code side. Maybe Larissa can also review PRs?! That would
> speed thing up.
> 
> Now, I believe that we should not have opened tickets forever with
> hundreds of comments in it.
> 
> The geoserver team uses the following rule:
> 
> - At least one review is needed (beg it to a friend if needed)
> - After addressing all the ISSUES found on the first review, the
> committer can merge. He should not wait for a second review to see if
> the new changes are ok, and then again and again...
> - Any "good to have" observations/comments, should be moved to a new
> ticket for future improvements.

I'm digging into this github app topic and it seems that setting up one
or more bots is more or less straightforward. Some of them allows to
mark a PR not mergable if at least one review is made. I don't know what
workflow is better to make things NOT complicated AND to speed up the
process WITHOUT loosing documentation quality.

For sure it is a good chance to discuss in the next HF

My 10 cents :)

Matteo