[Qgis-community-team] QGIS Documentation: increase the speed of documentation writing

[Alexandre Neto]

I tend to agree with Yves on this. Long review processes will just push
contributors away (if we ever attract them to contribute anyway).

On the limit, we must make sure each PR is accurate regarding its content,
it is well placed, and don't break the build. Enhancing wording and
grammar, fixing small typos, and improve Sphinx formatting could be done
afterwords, just before the release.

I think that would be the perfect way to spend Documentation funds, hiring
an English native tech writer (no need to know much of QGIS) to review the
documentation and fix wording, grammar, spelling, formatting and so on.

I am not saying we should merge PRs badly written and full of typos, but we
should not nitpick too much in search for perfection. Better to have some
low quality english documentation about a complex QGIS feature, than having
none.

I also agree that we may have to fix an already released version of the
documentation, and not wait months to release a perfect one. If QGIS LTR
receives patches to fix issues, why can't documentation do the same?

Regarding editing someone's else PR, I agree with Harrissou that, if a
valid PR is left untouched for too long after a review, instead of
abandoning it, we (core contributors) could/should take it as our own, fix
any remarkable issues and merge the content. That way, the work is not lost.

I am also in favor of allowing people to edit my typos and bad sphinx
formatting instead of asking me to do it, wasting twice the time. I am not
so keen to receive changes to wording and sentences without some
discussion. But I guess that is something each contributor has to decide
together with the reviewer.

Best regards,

Alex

PS: This being said, I will try to do some reviews (mainly to the content)
in the next days/weeks. Let's reduce the number of opened PRs! It make us
look bad! :-P




Yves Jacolin <yjacolin at free.fr> escreveu no dia quarta, 26/09/2018 às 08:35:

> Hello,
>
> Le 20/09/2018 à 10:25, DelazJ a écrit :
> > About some topics discussed in this thread, I'm less enthusiastic with
> > what I seem to understand.
> > I personally really prefer to merge a clean PR  without issues (and
> > sorry if ever I bothered some with all my (nit-?)picking), than
> > letting issues I'm aware of being merged and hope that someone else
> > (who?) will later treat them (when?). And if those issues are not
> > fixed before release, what about translators workload? Do we ask them
> > to translate the doc as is and if ever the issue is fixed, to
> > translate those strings again? Or do we consider that once a doc is
> > released, we do not touch it again (in which case what about the
> > issues we let pass in the PR)?
> > As said, maybe I misunderstand the topic.
>
> The topic seams clear: how to speed up (and, so, make PR easier). If I
> understood you well, you propose to not change anything.
>
> You said:
>
> > And if those issues are not fixed before release
>
> This is based in case of a release, what if we can't release the
> documentation before, let's say, one year? Why do we need to think to
> translator if we can't make a new release?
>
> Second, if we can make minor release of QGIs, why we can't do it for
> Documentation? Why can't we based the workflow on "release early,
> release often" princips? Translator will update a few string after each
> release, and so? Transifex allow to find previous translation from
> similar string, we won't change all the documentation, just some string.
> That's not seem a big work.
>
> I do still think that higher(st) quality is counter productive and I
> think (but not hope) that in few months we won't increase the number of
> contributor (rather decrease it).
>
> I am open to new propositions but not to let this process as it
> currently is.
>
> Y.
>
> --
> http://yjacolin.gloobe.org
>
>
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Alexandre Neto
---------------------
@AlexNetoGeo
http://sigsemgrilhetas.wordpress.com
http://gisunchained.wordpress.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20180926/2a423a01/attachment-0001.html>