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

Next Topic
 
classic Classic list List threaded Threaded
21 messages Options
12
Reply | Threaded
Open this post in threaded view
|

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

Yves Jacolin
Hello community and documentation contributors,

I would like to raise a discussion about the merge process in the QGIS
documentation.

My opinion is that the documentation process should be made easier in
order to increase the dynamic and the speed of feature documentation. I
do think we try to do our best to do some doc review, but probably not
enough and not fast enough. We should improve this and be faster in
order to be closer to the QGIS feature of the current public release,
then look at how to improve documentation later. If features are well
documented, we can probably pay for someone to proof read and fix
english issue.

In this purpose I would like to propose some keys to help merging PR and
I would like to get your opinion.

I would like to create three "levels" (a kind of guidelines) to
accept/refuse a PR, in a similar way as QGIS issues:

# Blocker (="need change" in review process)

Impossible to merge the PR because:

* Travis failed
* There is typos
* Write does not use any rst tags (:guilabel:, code-block, index, title,
etc.)

# No blocker but important (="comment" in review process)

PR can be merged but contributors can improve it before merging because:

* There is some missing rst tag
* Some sentences are not well written (I mean most of doc contributor
are not native english writer and so we are nos using the best english,
this email is a good illustration)

# Not important, just feedback (="comment" in review process)

PR can be merged, this is mainly subjective or small changes as:

* location of the contribution
* need screenshot (or update)
* fix a problem which has not been created by the PR
* Not enough description

Other contribution can create issue to not forget some of this changes
proposals.

We already agreed on the following, but better to tell it again: small
fix (add rst tag, fix typos) could be merged as soon as travis is a
success! So please, focus in small fix outside bigger PR :)

I am looking forward to read your opinion :)

Thanks to all for your great contributions!

Y.

--
http://yjacolin.gloobe.org



_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Alexandre Neto
Hi Yves, thanks for raising this matter.

+1 for making it easier to accept and merge contributions.

I would just swap the "There are typos" with the "location of the contributions" position. Mainly because the typos can be fixed later (unless there are major English problem that make the text difficult to understand), where contribution location can mess things up badly, and might be more difficult to untangle later.

Maybe, we should open dedicated tickets for reviewing and "sphinxifying" content for non important and no blocker merged PRs (or remove some tags and add some others (Screenshots, Needs English Review, Sphinx)).

Maybe we could use QGIS funds to hire someone that could tackle those "after content writing" tickets, which may be much easier than finding candidates that are both QGIS (advanced) users, good writing technical English, and familiar with sphinx syntax.

Thanks,

Alexandre Neto

Yves Jacolin <[hidden email]> escreveu no dia terça, 18/09/2018 às 16:45:
Hello community and documentation contributors,

I would like to raise a discussion about the merge process in the QGIS
documentation.

My opinion is that the documentation process should be made easier in
order to increase the dynamic and the speed of feature documentation. I
do think we try to do our best to do some doc review, but probably not
enough and not fast enough. We should improve this and be faster in
order to be closer to the QGIS feature of the current public release,
then look at how to improve documentation later. If features are well
documented, we can probably pay for someone to proof read and fix
english issue.

In this purpose I would like to propose some keys to help merging PR and
I would like to get your opinion.

I would like to create three "levels" (a kind of guidelines) to
accept/refuse a PR, in a similar way as QGIS issues:

# Blocker (="need change" in review process)

Impossible to merge the PR because:

* Travis failed
* There is typos
* Write does not use any rst tags (:guilabel:, code-block, index, title,
etc.)

# No blocker but important (="comment" in review process)

PR can be merged but contributors can improve it before merging because:

* There is some missing rst tag
* Some sentences are not well written (I mean most of doc contributor
are not native english writer and so we are nos using the best english,
this email is a good illustration)

# Not important, just feedback (="comment" in review process)

PR can be merged, this is mainly subjective or small changes as:

* location of the contribution
* need screenshot (or update)
* fix a problem which has not been created by the PR
* Not enough description

Other contribution can create issue to not forget some of this changes
proposals.

We already agreed on the following, but better to tell it again: small
fix (add rst tag, fix typos) could be merged as soon as travis is a
success! So please, focus in small fix outside bigger PR :)

I am looking forward to read your opinion :)

Thanks to all for your great contributions!

Y.

--
http://yjacolin.gloobe.org


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

ghtmtt
In reply to this post by Yves Jacolin
Hi Yves,

yes yes, +100 to spped up the merging process!

I also agree on the 3 steps that should make the way easier for all.

As Alexandre said: why not having some specific labels (sphinx fix) that
target some PR not blocker but that needs some special attention of some
sphinx expert.

For the typos: we have the amazing "fix me" link that also for skilled
writers is an immediate process to fix some small issues like typos.

Thanks for raising this

Cheers

Matteo
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

David Forel
Hi Folks -

I am a seasoned technical writer (American English), but only a beginner at QGIS (trying to climb the mountain).

I have read the instructions for submitting documentation to the project, but have not understood them at all; they are very complex.  Setting that aside, I am open to reviewing anyone's English text. I even understand British English (!).
. . . . . . . . . . . . . .
David Forel


On Tuesday, September 18, 2018, 11:37:22 AM MDT, matteo <[hidden email]> wrote:


Hi Yves,

yes yes, +100 to spped up the merging process!

I also agree on the 3 steps that should make the way easier for all.

As Alexandre said: why not having some specific labels (sphinx fix) that
target some PR not blocker but that needs some special attention of some
sphinx expert.

For the typos: we have the amazing "fix me" link that also for skilled
writers is an immediate process to fix some small issues like typos.

Thanks for raising this

Cheers

Matteo

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

pcav
In reply to this post by Alexandre Neto

Lots of good ideas, thanks everybody. Yves, could you please keep track of the discussion and implement its conclusions? I think we all agree on these. In case of doubt, please refer to PSC.

Thanks.


Il 09/18/2018 07:14 PM, Alexandre Neto ha scritto:
Hi Yves, thanks for raising this matter.

+1 for making it easier to accept and merge contributions.

I would just swap the "There are typos" with the "location of the contributions" position. Mainly because the typos can be fixed later (unless there are major English problem that make the text difficult to understand), where contribution location can mess things up badly, and might be more difficult to untangle later.

Maybe, we should open dedicated tickets for reviewing and "sphinxifying" content for non important and no blocker merged PRs (or remove some tags and add some others (Screenshots, Needs English Review, Sphinx)).

Maybe we could use QGIS funds to hire someone that could tackle those "after content writing" tickets, which may be much easier than finding candidates that are both QGIS (advanced) users, good writing technical English, and familiar with sphinx syntax.

Thanks,

Alexandre Neto

Yves Jacolin <[hidden email]> escreveu no dia terça, 18/09/2018 às 16:45:
Hello community and documentation contributors,

I would like to raise a discussion about the merge process in the QGIS
documentation.

My opinion is that the documentation process should be made easier in
order to increase the dynamic and the speed of feature documentation. I
do think we try to do our best to do some doc review, but probably not
enough and not fast enough. We should improve this and be faster in
order to be closer to the QGIS feature of the current public release,
then look at how to improve documentation later. If features are well
documented, we can probably pay for someone to proof read and fix
english issue.

In this purpose I would like to propose some keys to help merging PR and
I would like to get your opinion.

I would like to create three "levels" (a kind of guidelines) to
accept/refuse a PR, in a similar way as QGIS issues:

# Blocker (="need change" in review process)

Impossible to merge the PR because:

* Travis failed
* There is typos
* Write does not use any rst tags (:guilabel:, code-block, index, title,
etc.)

# No blocker but important (="comment" in review process)

PR can be merged but contributors can improve it before merging because:

* There is some missing rst tag
* Some sentences are not well written (I mean most of doc contributor
are not native english writer and so we are nos using the best english,
this email is a good illustration)

# Not important, just feedback (="comment" in review process)

PR can be merged, this is mainly subjective or small changes as:

* location of the contribution
* need screenshot (or update)
* fix a problem which has not been created by the PR
* Not enough description

Other contribution can create issue to not forget some of this changes
proposals.

We already agreed on the following, but better to tell it again: small
fix (add rst tag, fix typos) could be merged as soon as travis is a
success! So please, focus in small fix outside bigger PR :)

I am looking forward to read your opinion :)

Thanks to all for your great contributions!

Y.

--
http://yjacolin.gloobe.org


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

pcav
In reply to this post by David Forel

Thanks David, you are most welcomed. Please start reviewing, directly through GitHub, and submit your pull requests. In case of doubts or problems, please refer to this list.

All the best.


Il 09/18/2018 09:04 PM, David Forel ha scritto:
Hi Folks -

I am a seasoned technical writer (American English), but only a beginner at QGIS (trying to climb the mountain).

I have read the instructions for submitting documentation to the project, but have not understood them at all; they are very complex.  Setting that aside, I am open to reviewing anyone's English text. I even understand British English (!).
. . . . . . . . . . . . . .
David Forel


On Tuesday, September 18, 2018, 11:37:22 AM MDT, matteo [hidden email] wrote:


Hi Yves,

yes yes, +100 to spped up the merging process!

I also agree on the 3 steps that should make the way easier for all.

As Alexandre said: why not having some specific labels (sphinx fix) that
target some PR not blocker but that needs some special attention of some
sphinx expert.

For the typos: we have the amazing "fix me" link that also for skilled
writers is an immediate process to fix some small issues like typos.

Thanks for raising this

Cheers

Matteo

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

Alexandre Neto
Hi David,

I am preparing a video to show how to contribute to QGIS Documentation in an easy way. Unfortunatly I do not have an estimated release date for it. Please fell free to reach out if you have any questions that are blocking you.

Alexandre Neto

PS: Regarding the mailing list, make sure you are using the same email that you subscribed the mailing list. If you the original email forwarding to another inbox, that won't work. Also, e.g., for gmail [hidden email] is the same as [hidden email], but for the mailing lists, they are totally different addresses.

Paolo Cavallini <[hidden email]> escreveu no dia quarta, 19/09/2018 às 06:24:

Thanks David, you are most welcomed. Please start reviewing, directly through GitHub, and submit your pull requests. In case of doubts or problems, please refer to this list.

All the best.


Il 09/18/2018 09:04 PM, David Forel ha scritto:
Hi Folks -

I am a seasoned technical writer (American English), but only a beginner at QGIS (trying to climb the mountain).

I have read the instructions for submitting documentation to the project, but have not understood them at all; they are very complex.  Setting that aside, I am open to reviewing anyone's English text. I even understand British English (!).
. . . . . . . . . . . . . .
David Forel


On Tuesday, September 18, 2018, 11:37:22 AM MDT, matteo [hidden email] wrote:


Hi Yves,

yes yes, +100 to spped up the merging process!

I also agree on the 3 steps that should make the way easier for all.

As Alexandre said: why not having some specific labels (sphinx fix) that
target some PR not blocker but that needs some special attention of some
sphinx expert.

For the typos: we have the amazing "fix me" link that also for skilled
writers is an immediate process to fix some small issues like typos.

Thanks for raising this

Cheers

Matteo

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

Yves Jacolin
In reply to this post by pcav

Thank you for your feedback, just some thought about your first feedback.

"Blocker" level should be fast and easy to fix, so fixing some typos is easy and generally doesn't need too much discussion.

"Not important" level: this is probably not the best word to describe this level because it could be important. What I mean is that it need more discussion to find a common consensus. For example, location of a description.

For me, typos in a text is a problem. If the location of the description is not the best one, I probably can find it (search with Google or so), this is not a problem that occurs often and as said, if someone says this is not a good location, if the contributor agreed he can move it.

Finally, about pushing some fix in a branch of other contributor: I think this shouldn't be done. I see a branch as a personal work and pushing a commit, quiet invasive. Personally, I commit with amend flag then "push force" most of the time in my branch.

@paolo, as soon as we find a consensus, we will write it into the guidelines. I will then help to find someone to be paid to write documentation.

Thanks,

Y.

Le 19/09/2018 à 07:21, Paolo Cavallini a écrit :

Lots of good ideas, thanks everybody. Yves, could you please keep track of the discussion and implement its conclusions? I think we all agree on these. In case of doubt, please refer to PSC.

Thanks.


Il 09/18/2018 07:14 PM, Alexandre Neto ha scritto:
Hi Yves, thanks for raising this matter.

+1 for making it easier to accept and merge contributions.

I would just swap the "There are typos" with the "location of the contributions" position. Mainly because the typos can be fixed later (unless there are major English problem that make the text difficult to understand), where contribution location can mess things up badly, and might be more difficult to untangle later.

Maybe, we should open dedicated tickets for reviewing and "sphinxifying" content for non important and no blocker merged PRs (or remove some tags and add some others (Screenshots, Needs English Review, Sphinx)).

Maybe we could use QGIS funds to hire someone that could tackle those "after content writing" tickets, which may be much easier than finding candidates that are both QGIS (advanced) users, good writing technical English, and familiar with sphinx syntax.

Thanks,

Alexandre Neto

Yves Jacolin <[hidden email]> escreveu no dia terça, 18/09/2018 às 16:45:
Hello community and documentation contributors,

I would like to raise a discussion about the merge process in the QGIS
documentation.

My opinion is that the documentation process should be made easier in
order to increase the dynamic and the speed of feature documentation. I
do think we try to do our best to do some doc review, but probably not
enough and not fast enough. We should improve this and be faster in
order to be closer to the QGIS feature of the current public release,
then look at how to improve documentation later. If features are well
documented, we can probably pay for someone to proof read and fix
english issue.

In this purpose I would like to propose some keys to help merging PR and
I would like to get your opinion.

I would like to create three "levels" (a kind of guidelines) to
accept/refuse a PR, in a similar way as QGIS issues:

# Blocker (="need change" in review process)

Impossible to merge the PR because:

* Travis failed
* There is typos
* Write does not use any rst tags (:guilabel:, code-block, index, title,
etc.)

# No blocker but important (="comment" in review process)

PR can be merged but contributors can improve it before merging because:

* There is some missing rst tag
* Some sentences are not well written (I mean most of doc contributor
are not native english writer and so we are nos using the best english,
this email is a good illustration)

# Not important, just feedback (="comment" in review process)

PR can be merged, this is mainly subjective or small changes as:

* location of the contribution
* need screenshot (or update)
* fix a problem which has not been created by the PR
* Not enough description

Other contribution can create issue to not forget some of this changes
proposals.

We already agreed on the following, but better to tell it again: small
fix (add rst tag, fix typos) could be merged as soon as travis is a
success! So please, focus in small fix outside bigger PR :)

I am looking forward to read your opinion :)

Thanks to all for your great contributions!

Y.

--
http://yjacolin.gloobe.org


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
http://yjacolin.gloobe.org

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

pcav
Hi Yves,


Il 09/19/2018 03:50 PM, Yves Jacolin ha scritto:
>
> @paolo, as soon as we find a consensus, we will write it into the
> guidelines. I will then help to find someone to be paid to write
> documentation.
>
thanks a lot for this, much appreciated.
All the best.

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/



_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

signature.asc (201 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

David Forel
In reply to this post by Alexandre Neto
Hi Folks -

I found "qgis/QGIS-Documentation" on github.  I presume this is the right repository, but I welcome your confirmation.

The "readme.rst" says nothing about 3.x and this disturbs me.  In my knowledge of software releases, a move from a 2.x to a 3.x is significant, and I imagine is highly disruptive to the existing documentation.  I imagine the documentation of 2.x that is in 3.x must have some gaping holes and is confusing where it assumes the user is in 2.x.

My point is not to complain; rather, I wonder whether instead of simply making better English in 2.x documentation that is in 3.x, someone might guide me to workflows that need to be revised or even created for 3.x.

Respectfully, David Forel



On Wednesday, September 19, 2018, 3:01:24 AM MDT, Alexandre Neto <[hidden email]> wrote:


Hi David,

I am preparing a video to show how to contribute to QGIS Documentation in an easy way. Unfortunatly I do not have an estimated release date for it. Please fell free to reach out if you have any questions that are blocking you.

Alexandre Neto

PS: Regarding the mailing list, make sure you are using the same email that you subscribed the mailing list. If you the original email forwarding to another inbox, that won't work. Also, e.g., for gmail [hidden email] is the same as [hidden email], but for the mailing lists, they are totally different addresses.

Paolo Cavallini <[hidden email]> escreveu no dia quarta, 19/09/2018 às 06:24:

Thanks David, you are most welcomed. Please start reviewing, directly through GitHub, and submit your pull requests. In case of doubts or problems, please refer to this list.

All the best.


Il 09/18/2018 09:04 PM, David Forel ha scritto:
Hi Folks -

I am a seasoned technical writer (American English), but only a beginner at QGIS (trying to climb the mountain).

I have read the instructions for submitting documentation to the project, but have not understood them at all; they are very complex.  Setting that aside, I am open to reviewing anyone's English text. I even understand British English (!).
. . . . . . . . . . . . . .
David Forel


On Tuesday, September 18, 2018, 11:37:22 AM MDT, matteo [hidden email] wrote:


Hi Yves,

yes yes, +100 to spped up the merging process!

I also agree on the 3 steps that should make the way easier for all.

As Alexandre said: why not having some specific labels (sphinx fix) that
target some PR not blocker but that needs some special attention of some
sphinx expert.

For the typos: we have the amazing "fix me" link that also for skilled
writers is an immediate process to fix some small issues like typos.

Thanks for raising this

Cheers

Matteo

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

Yves Jacolin

Hello David,


Le 20/09/2018 à 02:45, David Forel a écrit :
Hi Folks -

I found "qgis/QGIS-Documentation" on github.  I presume this is the right repository, but I welcome your confirmation.
I confirm!

The "readme.rst" says nothing about 3.x and this disturbs me.  In my knowledge of software releases, a move from a 2.x to a 3.x is significant, and I imagine is highly disruptive to the existing documentation.  I imagine the documentation of 2.x that is in 3.x must have some gaping holes and is confusing where it assumes the user is in 2.x.
The README file is not up to date :) We should add 3.x releases, probably remove 2.x links and update the contacts list.

My point is not to complain; rather, I wonder whether instead of simply making better English in 2.x documentation that is in 3.x, someone might guide me to workflows that need to be revised or even created for 3.x.
PR welcome :) Do you have any idea how to do this? Read this https://docs.qgis.org/2.18/en/docs/documentation_guidelines/first_contribution.html#using-github-web-interface if there are any problem, we can help!

Many thanks!

Y.

Respectfully, David Forel



On Wednesday, September 19, 2018, 3:01:24 AM MDT, Alexandre Neto [hidden email] wrote:


Hi David,

I am preparing a video to show how to contribute to QGIS Documentation in an easy way. Unfortunatly I do not have an estimated release date for it. Please fell free to reach out if you have any questions that are blocking you.

Alexandre Neto

PS: Regarding the mailing list, make sure you are using the same email that you subscribed the mailing list. If you the original email forwarding to another inbox, that won't work. Also, e.g., for gmail [hidden email] is the same as [hidden email], but for the mailing lists, they are totally different addresses.

Paolo Cavallini <[hidden email]> escreveu no dia quarta, 19/09/2018 às 06:24:

Thanks David, you are most welcomed. Please start reviewing, directly through GitHub, and submit your pull requests. In case of doubts or problems, please refer to this list.

All the best.


Il 09/18/2018 09:04 PM, David Forel ha scritto:
Hi Folks -

I am a seasoned technical writer (American English), but only a beginner at QGIS (trying to climb the mountain).

I have read the instructions for submitting documentation to the project, but have not understood them at all; they are very complex.  Setting that aside, I am open to reviewing anyone's English text. I even understand British English (!).
. . . . . . . . . . . . . .
David Forel


On Tuesday, September 18, 2018, 11:37:22 AM MDT, matteo [hidden email] wrote:


Hi Yves,

yes yes, +100 to spped up the merging process!

I also agree on the 3 steps that should make the way easier for all.

As Alexandre said: why not having some specific labels (sphinx fix) that
target some PR not blocker but that needs some special attention of some
sphinx expert.

For the typos: we have the amazing "fix me" link that also for skilled
writers is an immediate process to fix some small issues like typos.

Thanks for raising this

Cheers

Matteo

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team


_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
http://yjacolin.gloobe.org

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

Anita Graser
In reply to this post by Yves Jacolin


On Wed, Sep 19, 2018 at 3:50 PM Yves Jacolin <[hidden email]> wrote:
Finally, about pushing some fix in a branch of other contributor: I think this shouldn't be done. I see a branch as a personal work and pushing a commit, quiet invasive. Personally, I commit with amend flag then "push force" most of the time in my branch.

As someone who has only used the web interface to contribute to documentation, I would strongly prefer it if reviewers would fix directly in my branch. At least I didn't see any ways on the web to use amend flag to incorporate the proposed changes. It would certainly speed up things.

Regards,
Anita



_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

Yves Jacolin



Le 20/09/2018 à 09:40, Anita Graser a écrit :


On Wed, Sep 19, 2018 at 3:50 PM Yves Jacolin <[hidden email]> wrote:
Finally, about pushing some fix in a branch of other contributor: I think this shouldn't be done. I see a branch as a personal work and pushing a commit, quiet invasive. Personally, I commit with amend flag then "push force" most of the time in my branch.

As someone who has only used the web interface to contribute to documentation, I would strongly prefer it if reviewers would fix directly in my branch. At least I didn't see any ways on the web to use amend flag to incorporate the proposed changes. It would certainly speed up things.

Regards,
Anita,

You can do with the web interface but when you merge the PR. I added a screenshot. Squashing commit is a good practice to have a clean commit list.

Y.
-- 
http://yjacolin.gloobe.org

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

Spectacle.M10839.png (77K) Download Attachment
signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

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

DelazJ
Hi,

Yves, in that case you assume the PR is good enough and ready to merge, which is not the context Anita and Alexandre are referring to.

Personally, I prefer to add comments and let the contributor fix the issues rather than pushing changes to his branch. This can indeed look intrusive, reason why I applied it to few people. BUT there are cases where pushing changes is more a help than a bother:
- for people facing a conflict that cannot be resolved through the web interface (like Anita) or do not know git, it helps to move forward. I prefer keeping all in the single PR rather than opening a new PR with a loss of comments/suggestion history and a waste of time for everybody.
- when the PR seems abandoned: no reply/modification applied for weeks from the contributor. Reason why, Yves, I pushed changes to your PR two days ago. Sorry if ever that bothered you but I thought it would help to speed the merge (and did not know your position on this process).
Another (less intrusive?) option for the latter case can be to PR against the branch of the contributor and hope he merges it.

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.

Regards,
Harrissou

Le jeu. 20 sept. 2018 à 10:00, Yves Jacolin <[hidden email]> a écrit :



Le 20/09/2018 à 09:40, Anita Graser a écrit :


On Wed, Sep 19, 2018 at 3:50 PM Yves Jacolin <[hidden email]> wrote:
Finally, about pushing some fix in a branch of other contributor: I think this shouldn't be done. I see a branch as a personal work and pushing a commit, quiet invasive. Personally, I commit with amend flag then "push force" most of the time in my branch.

As someone who has only used the web interface to contribute to documentation, I would strongly prefer it if reviewers would fix directly in my branch. At least I didn't see any ways on the web to use amend flag to incorporate the proposed changes. It would certainly speed up things.

Regards,
Anita,

You can do with the web interface but when you merge the PR. I added a screenshot. Squashing commit is a good practice to have a clean commit list.

Y.
-- 
http://yjacolin.gloobe.org
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

Yves Jacolin
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..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team

signature.asc (484 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: [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 <[hidden email]> 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..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

DelazJ
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 <[hidden email]> 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 <[hidden email]> 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..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

Alexandre Neto
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

DelazJ
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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com
--
Alexandre Neto
---------------------
@AlexNetoGeo
http://gisunchained.wordpress.com

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
Reply | Threaded
Open this post in threaded view
|

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

pcav
In reply to this post by Alexandre Neto
Hi Alex,


Il 09/28/2018 11:48 AM, Alexandre Neto ha scritto:
> 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.
>
>
I believe PSC decision takes this into account.
Your opinion and input welcome.
All the best.

--
Paolo Cavallini - www.faunalia.eu
QGIS.ORG Chair:
http://planet.qgis.org/planet/user/28/tag/qgis%20board/

_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
[hidden email]
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
12