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

Mon Oct 1 08:49:38 PDT 2018

Hi,

Among the  people interested in the documentation writing call, some
proposed to help on reviewing. I don't know if they refer to general doc
review or PRs review but depending on their interest, maybe some
interventions can be postponed to the finishing touches...

Harrissou

Le ven. 28 sept. 2018 à 11:49, Alexandre Neto <senhor.neto at gmail.com> a
écrit :

> Having a professional review before the release was just a suggestion. Of
> course we still need people to write the docs anyway.
>
> Paolo, do you think that would make sense? To spend some documentation
> money in reviewing the documentation? Probably mainly the User's Manual I
> guess. I don't know how much is already allocated to content writing.
>
> thanks
>
> DelazJ <delazj at gmail.com> escreveu no dia sexta, 28/09/2018 às 09:22:
>
>> Hi,
>>
>> Yves, I proposed nothing but I did not propose to do nothing. I was
>> asking questions to better understand where the issue resides (I have one
>> or two situations in mind that may be related to this discussion) but,
>> anyway...
>> I'm not asking for statu quo. Whatever is found that improves the process
>> without deprecating the quality of docs, I'm in. And this last part is what
>> was questioning me. Fortunately, I get an answer (that I overlooked in
>> previous messages) from Alex: we'd hire someone who will make a review of
>> the docs to fix what (s)he can fix before the release. OK. This was not the
>> case for 2.18 and if I'm not wrong it was the plan for 2.14 (or 2.8?)  but
>> I'm not sure how far this was effective... So if that's the route, we
>> should make sure we really take it.
>>
>> About releases plan, it's already the case. 2.18 docs has been released
>> but it did not prevent it to get new fixes/improvement. And then pushed
>> again to Transifex. Richard manages that pretty well as long as he's made
>> aware of the need (btw, I wonder if no new fixes have been merged since the
>> last push - same for qgis.org?). My fear was that "small mistakes" we
>> let pass to the docs because of "speed merging" are translated and then
>> fixed and retranslated. Yes it may be few strings here and there. But it
>> involves x language contributors instead of having involved one English
>> contributor at the beginning. And if it's not retranslated, you end up with
>> mixed languages paragraphs in the same section, which is ugly and
>> deprecates translated doc quality. But I understand that those errors won't
>> reach translators because a hired reviewer would fix them before the
>> release. why not...?
>>
>> From my side, I agree with less nitpicking, which I guess, does not mean
>> to not point the issues I see; the writer is free to follow or not,
>> depending on what is retained in this discussion and any committer can
>> merge if the PR satisfies the minimal requirement.
>> That said, whatever rule is set, it would make sense and be applied only
>> if there are people who write (and, for some reasons, are in a hurry for
>> merging) and IF there are people to review and comment (which unfortunately
>> is far from being the case - recent months show that a PR has to stay
>> around a week before any review when not merged without). Hoping that
>> changes...
>>
>> Regards,
>> Harrissou
>>
>>  Le mer. 26 sept. 2018 à 13:26, Alexandre Neto <senhor.neto at gmail.com> a
>> écrit :
>>
>>> 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
>>>
>> --
> 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/20181001/62f52f9c/attachment-0001.html>