Re: [Qgis-community-team] [SeasonOfDocs] QGIS writing tasks need help

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [Qgis-community-team] [SeasonOfDocs] QGIS writing tasks need help

Cameron Shorter

Hi folks,

I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

Ideas I'm considering based on the conversations so far:

* There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

* OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

* "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

* The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

* QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

* With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

* Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

* I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

----

Please respond to this email with your ideas. I'll really appreciate the help.

What follows are the emails and ideas I've based the above thoughts upon.

Warm regards, Cameron

----


Matteo's suggestions:

  • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
  • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
  • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
  • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
Hi,

I agree with Jo's respone to Camerons question. 

Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

Regards

Andrew

On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
HI All,

<snip>

Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

Regards

Jo

On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

Warm regards, Cameron


On 10/4/19 10:13 pm, Nick Bearman wrote:
<snip>

I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

_______________________________________________
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] [SeasonOfDocs] QGIS writing tasks need help

Andrew Jeffrey
Hi Cameron,

Here is my suggestions for QGIS tasks, nothing new from conversations we have had in the past. Like i've said before my biggest worry is offending someone on the documentation team, I think QGIS does a great job at documentation these are just items ove noticed from my involvement in the Australian user group.
  • Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.
  • Review structure of current documentation, provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? I'm not sure but a writer could assist us with the best practice structure?
  • Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so lets make this section so accurate and clear that anyone can pick it up.
  • Get documentation mentors (someone alread familiar with documenting) to assist want to be documenters knock off some of the doc items marked as "easy". 
For the most part I think the QGIS documentation is good and quiet in-depth, just at times a difficult to navigate and find content.

Happy for people to question me on these, or have a discussion about QGIS items you would find valuable.

Thank
Andrew

On Sun, Apr 21, 2019 at 8:22 AM Cameron Shorter <[hidden email]> wrote:

Hi folks,

I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

Ideas I'm considering based on the conversations so far:

* There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

* OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

* "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

* The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

* QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

* With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

* Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

* I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

----

Please respond to this email with your ideas. I'll really appreciate the help.

What follows are the emails and ideas I've based the above thoughts upon.

Warm regards, Cameron

----


Matteo's suggestions:

  • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
  • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
  • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
  • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
Hi,

I agree with Jo's respone to Camerons question. 

Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

Regards

Andrew

On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
HI All,

<snip>

Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

Regards

Jo

On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

Warm regards, Cameron


On 10/4/19 10:13 pm, Nick Bearman wrote:
<snip>

I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254
_______________________________________________
SeasonOfDocs mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/seasonofdocs

_______________________________________________
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] [SeasonOfDocs] QGIS writing tasks need help

Cameron Shorter
Richard,

I think you might have missed a subtle difference between Season Of Docs
and Summer Of Code.

* Summer Of Code targets JUNIOR developers.

* Season Of Docs targets SENIOR writers.

Senior writers could typically be tasked with structuring documentation
to simplify navigation and target different learning styles, or
explaining difficult concepts clearly and concisely.

 From your list, a senior writer could review the Training Manual and
the Gentle Introduction (and others) to see how best to structure.

With regards to extra features needing documenting that you mention. Are
you able to quantify the current status of this? What percentage of
features have docs / have docs that need updating / have no docs?

Andrew, thanks for sharing your metrics from first time users. Your
suggested tasks are well defined, which would make them easier to hand
over to a technical writer for implementation. I'll be interested to
hear feedback from others on this.


On 21/4/19 8:50 pm, Richard 🌍 Duivenvoorde wrote:

> Hi Cameron,
>
> In my opinion we have a rather good process (but therefor for newcomers
> complex?) of writing the docs.
>
> Our weakspots:
>
> - writing rst in 'QGIS doc style' is not trivial (in my opinion): adding
> images is well, tricky, the different kind of 'substitutions' to use,
> the building process, git handling, keeping images uptodate (we have
> been busy with machinery to do this automagically) etc etc.
> Not sure if this is something to be picked up by juniors though.
> I thought about having a process like: juniors create images + text and
> others integrate it in the Docs. BUT... tried that last month: received
> a Word Doc with good docs about Mesh Layers, and thought to wedge that
> into rst... took me a lot of time ... too much... so this 2-step writing
> is not what I would prefer now.
>
> Some wild ideas:
> - because of all the information, it is hard to keep 'overview', if we
> could find something for that?
> - About Andrew's note about people asking how to do the 'easy things'
> like opening datasets:  I sometimes think we humans want things to
> happen too easy: having complex data or crs's it is hard to make it
> 'easy'. We have a Training Manual and a Gentle Introduction... Maybe
> these could be 'merged' in one uptodate one? (others: is that doable?).
> Or add a better 'how to add data into QGIS chapter in (one of) those'?
> - we have been talking about updating the build process to have a zip of
> the docs IN QGIS for offline use (but this is not a writer task)..
>
> But we have a huge list of new features which can be used to write docs
> for in 'bite sized parts':
> https://github.com/qgis/QGIS-Documentation/issues
>
> But again: it is for junior writers (or QGIS users) maybe hard to find
> WHAT exactly to write, it is even hard for experienced writers often...
>
> So maybe (my) conclusion is that we do not have that much 'low hanging'
> fruit?
> Others?
>
> Regards,
>
> Richard Duivenvoorde
>
> ps: what about a 'doc team heads up again'?
>
> On 21/04/2019 06.10, Andrew Jeffrey wrote:
>> Hi Cameron,
>>
>> Here is my suggestions for QGIS tasks, nothing new from conversations we
>> have had in the past. Like i've said before my biggest worry is
>> offending someone on the documentation team, I think QGIS does a great
>> job at documentation these are just items ove noticed from my
>> involvement in the Australian user group.
>>
>>    * Get assistance from writers to create a simple, and clear
>>      "quickstart". /WHY? Because 11 of the 26 threads started in 2019 on
>>      the Australian user group are related to getting started, loading
>>      and exporting data. People indicate that they have referred to the
>>      documentation but are still lost./
>>    * Review structure of current documentation, provide clear separation
>>      of tasks. /WHY? Because there is a "Getting started" section in the
>>      user manual and also a separate documentation section on "Getting
>>      started with GIS" - Which route does a new user take? And is the
>>      best place for Getting started material to be nested in other
>>      material? I'm not sure but a writer could assist us with the best
>>      practice structure?/
>>    * Writers to review the language and readability of the QGIS "Step by
>>      Step contribution" (This is documentation for making documentation
>>      contributions).
>>      - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html
>>      - /WHY? This guide walks a user through making a contirbution to the
>>      QGIS documentation. I don't believe the method for maintaining
>>      documentation will change, so lets make this section so accurate and
>>      clear that anyone can pick it up./
>>    * Get documentation mentors (someone alread familiar with documenting)
>>      to assist want to be documenters knock off some of the doc items
>>      marked as "easy".
>>
>> For the most part I think the QGIS documentation is good and quiet
>> in-depth, just at times a difficult to navigate and find content.
>>
>> Happy for people to question me on these, or have a discussion about
>> QGIS items you would find valuable.
>>
>> Thank
>> Andrew
>>
>> On Sun, Apr 21, 2019 at 8:22 AM Cameron Shorter
>> <[hidden email] <mailto:[hidden email]>> wrote:
>>
>>      Hi folks,
>>
>>      I'm struggling to compile QGIS writing tasks for SeasonOfDocs which
>>      are as compelling as Jo and Maria have put together for GeoNetwork:
>>
>>      https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork
>>
>>      I'm hoping that those of you who have used QGIS docs can list
>>      strengths and then be fully transparent about its weaknesses. If we
>>      don't have much of a problem, something requiring senior technical
>>      writer expertise, then why would Google want to help us? There will
>>      be plenty of worthy projects for Google to select from.
>>
>>      We have 3 days (till 23 April) to respond. Could you please help by
>>      brainstorming ideas in this email thread. I'll commit to compiling
>>      them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS
>>      . (Although feel free to update it yourself.)
>>
>>      Ideas I'm considering based on the conversations so far:
>>
>>      * There appears to be a high technical barrier to entry which makes
>>      it hard for new users to engage with improving QGIS docs. Is this
>>      so? What writing tasks could we put in place to address this?
>>
>>      * OSGeoLive has successfully attracted authors from ~ 50 projects to
>>      write Quickstarts and Project Overviews based on clear templates and
>>      writing guides. Would a template/writing guide be useful for QGIS?
>>      For what doc types? Workshops? Tutorials? (I'm suspecting these to
>>      be in the sweet spot for us, as they could be rolled out through
>>      OSGeoLive to other projects).
>>
>>      * "/Training materials are generally tailored to a customer, their
>>      technical use case, using sample maps from the customer's location
>>      in the world. This makes it difficult to develop consolidated
>>      material that works for everyone". /However/, "there's a really big
>>      need for standard training materials- and also if possible the kind
>>      of training materials that could be used for schools, to try to
>>      break the monopoly that certain proprietary companies have on that
>>      area."/ How can we define this task more clearly?
>>
>>      * The GeoNetwork team have provided an honest statement about the
>>      quality and completeness of their documentation. Does QGIS
>>      documentation have similar limitations? (My initial skim over docs
>>      suggest that the quality might be better, but I could be wrong.)
>>
>>      * QGIS has had a major feature update from 2.18 to 3.4.x. I suspect
>>      we should talk about this? What documentation still needs to be
>>      updated or improved as a consequence?
>>
>>      * With a rapidly innovating product like QGIS, with large
>>      documentation base, we could be running into challenges around
>>      maintenance and sustainability. Do you consider this a problem? If
>>      so, can you provide examples we can reference? Do you have
>>      suggestions on writing tasks to address this?
>>
>>      * Matteo mentions an issue tracker with over 400 writing tasks in
>>      it. How do we resource the management of these issues? We likely
>>      won't be allocated a *senior* writer to action such a list (Google's
>>      target for this initiative), but we might get a junior writer. This
>>      might not be supported until future Google writing initiatives,
>>      based on our identified need for such a role.
>>
>>      * I'm aware that there are multiple QGIS training courses on the
>>      web, some which are free and open. Could you identify those that a
>>      tech writer should consider. You can list in the "Resources:" list
>>      in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I
>>      notice that much of the training on the web is still based on
>>      version 2.18. Should we suggest effort be dedicated to updating them
>>      to 3.4?
>>
>>      ----
>>
>>      Please respond to this email with your ideas. I'll really appreciate
>>      the help.
>>
>>      What follows are the emails and ideas I've based the above thoughts
>>      upon.
>>
>>      Warm regards, Cameron
>>
>>      ----
>>
>>
>>      Matteo's suggestions:
>>
>>        * Pyqgis cookbook code snipped are now automatically tested,
>>          meaning that every new contribution will be rock solid and code
>>          snippets can be taken "as they are" and pasted in QGIS
>>        * Change the doc style to the more readable Read-The-Docs vanilla
>>          theme (fully supported by sphinx). A live example
>>          here https://qgis.org/test/en/.
>>        * Besides from contents, writing documentation isn't easy because
>>          of the complex framework (sphinx, git, github, etc). Improving
>>          the WYSIWYG github editor would be a great enhancement
>>        * Cleaning the issue tracker in github (> 400 issue now) in many
>>          different ways: verifying issues, closing duplicates, make order
>>          in the labels, etc
>>
>>      On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
>>>      Hi,
>>>
>>>      I agree with Jo's respone to Camerons question.
>>>
>>>      Training materials are generally tailored to a type of customer
>>>      and I this believe makes it difficult to develop consolidated
>>>      material that works for everyone. The similarities I do see in
>>>      training material though is the basics, the kind of basics that
>>>      are taught to new users like those in the education space.
>>>
>>>      As Jo mentioned there is potential here to break a monolopy in
>>>      this space, and get exposure to new users early in their
>>>      development. What makes this even better is a solid training
>>>      material base owned by the community can be used by anyone
>>>      creating training material, providing a consistent training base
>>>      whether you learn in your own time online or go to trainer "A".
>>>      Effectively consolidating the "QGIS beginner" training material.
>>>
>>>      Regards
>>>
>>>      Andrew
>>>
>>>      On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]
>>>      <mailto:[hidden email]>> wrote:
>>>
>>>          HI All,
>>>
>>>          <snip>
>>>
>>>          Secondly- Cameron's question about QGIS courses- we also run
>>>          QGIS training courses in the UK, and I think there's a fairly
>>>          wide market, both geographically, and in the types of
>>>          customer. We are focused on integration with cloud
>>>          technologies, such as delivering QGIS via AWS AppStream, and
>>>          less on teaching people to use all of the functionality, for
>>>          example for higher-end processing and analysis. Having said
>>>          that, I think there's a really big need for standard training
>>>          materials- and also if possible the kind of training materials
>>>          that could be used for schools, to try to break the monopoly
>>>          that certain proprietary companies have on that area.
>>>
>>>          Regards
>>>
>>>          Jo
>>>
>>>          On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter
>>>          <[hidden email] <mailto:[hidden email]>>
>>>          wrote:
>>>
>>>              Thanks for the introduction Nick. One thing that puzzles
>>>              me is that there appears to be a lot of people setting up
>>>              QGIS training courses and I would have thought it would be
>>>              beneficial of these separate initiatives were to become
>>>              more consolidated.
>>>
>>>              I'd expect that consolidating workshops would be a very
>>>              valuable task, as it would focus the community together.
>>>
>>>              It would also be a suitably challenging task to bring
>>>              multiple threads together, and something that would be
>>>              worthy of a senior technical writer's expertise.
>>>
>>>              What are people's thoughts on the current state of
>>>              available QGIS training courses? Is there potential to
>>>              consolidate? Or is everyone tailoring to their unique user
>>>              base?
>>>
>>>              Warm regards, Cameron
>>>
>>>
>>>              On 10/4/19 10:13 pm, Nick Bearman wrote:
>>>>              <snip>
>>>>
>>>>              I'm keen to learn how to contribute more effectively,
>>>>              particularly to QGIS documentation, and I am also looking
>>>>              to run a workshop on how to contribute to OS
>>>>              documentation at upcoming FOSS4G UK event in Edinburgh,
>>>>              UK in Sept.
>>>>
>>>>              I am familiar with Git/GitHub and Markdown. The RST
>>>>              format of the QGIS Documentation site sometimes eludes
>>>>              me! I look forward to working with you all.
>>>>
>>      --
>>      Cameron Shorter
>>      Technology Demystifier
>>      Open Technologies and Geospatial Consultant
>>
>>      M +61 (0) 419 142 254
>>
>>      _______________________________________________
>>      SeasonOfDocs mailing list
>>      [hidden email] <mailto:[hidden email]>
>>      https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
>>
>> _______________________________________________
>> 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
>>
--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

_______________________________________________
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] [SeasonOfDocs] QGIS writing tasks need help

Cameron Shorter
In reply to this post by Andrew Jeffrey

Richard, it seems from your last response that you hadn't read Nick's email. Maybe you are not subscribed to [hidden email]

Nick, you also might be able to help quantify how much new material needs to be created, and where to source the new material from?

I'll let the QGIS community reply about how to best communicate with them. (I've heard others ask about the best way to communicate with QGIS doc team, so I'm also interested in the answer.)

On 21/4/19 8:23 pm, Nick Bearman wrote:
Hi Cameron and everyone,

I think your and Andrew's list is fairly comprehensive. I would agree the documentation is good, but I also find it hard to navigate. 

I would add that a fair chunk of the tasks that need to be done are the new features (brought in at different versions) which need to be included. There is probably a fair chunk of this that material does exist for (e.g. a blog post on a new feature) that could just be copied over and tidied up (with ok of the original author) into QGIS documentation. 

I think we probably should have reached out to the QGIS community a bit more, but I'm not very clear on how to do that! (Cameron, did you get any replies from the QGIS Community list)? Probably I have just not looked enough to find the right methods to contact them. 

I have had interaction with Harrissou Sant-anna https://github.com/DelazJ on GitHub and they seem quite active, and Alessandro Pasotti https://github.com/elpaso who has commented on a few of my PRs. However I can't work how how to message them through GitHub! Perhaps they are on the qgis-community-team list?!

Please do ask questions, make suggestions etc. !

Best wishes,
Nick.

On Sun, 21 Apr 2019 at 05:10, Andrew Jeffrey <[hidden email]> wrote:
Hi Cameron,

Here is my suggestions for QGIS tasks, nothing new from conversations we have had in the past. Like i've said before my biggest worry is offending someone on the documentation team, I think QGIS does a great job at documentation these are just items ove noticed from my involvement in the Australian user group.
  • Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.
  • Review structure of current documentation, provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? I'm not sure but a writer could assist us with the best practice structure?
  • Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so lets make this section so accurate and clear that anyone can pick it up.
  • Get documentation mentors (someone alread familiar with documenting) to assist want to be documenters knock off some of the doc items marked as "easy". 
For the most part I think the QGIS documentation is good and quiet in-depth, just at times a difficult to navigate and find content.

Happy for people to question me on these, or have a discussion about QGIS items you would find valuable.

Thank
Andrew

On Sun, Apr 21, 2019 at 8:22 AM Cameron Shorter <[hidden email]> wrote:

Hi folks,

I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

Ideas I'm considering based on the conversations so far:

* There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

* OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

* "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

* The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

* QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

* With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

* Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

* I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

----

Please respond to this email with your ideas. I'll really appreciate the help.

What follows are the emails and ideas I've based the above thoughts upon.

Warm regards, Cameron

----


Matteo's suggestions:

  • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
  • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
  • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
  • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
Hi,

I agree with Jo's respone to Camerons question. 

Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

Regards

Andrew

On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
HI All,

<snip>

Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

Regards

Jo

On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

Warm regards, Cameron


On 10/4/19 10:13 pm, Nick Bearman wrote:
<snip>

I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254
_______________________________________________
SeasonOfDocs mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/seasonofdocs
_______________________________________________
SeasonOfDocs mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/seasonofdocs


--
Nick Bearman
01209 808910 | 07717745715

Due to my own life/work balance, you may get emails from me outside of normal working hours. Please do not feel any pressure to respond outside of your own working pattern.
-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254

_______________________________________________
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] [SeasonOfDocs] QGIS writing tasks need help

Cameron Shorter
In reply to this post by Cameron Shorter
I've updated the QGIS Season of Docs ideas, based on ideas on this list so far. Thanks for your ideas, especially thanks to Andrew for writing it out so clearly.

QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. QGIS core documentation is comprehensive and there is a diverse ecosystem of organisations and people who have created QGIS workshops and training courses. However, it is challenging for documenters to keep up with QGIS’s rapid innovation, to sustainably keep the breadth of documentation current, consistent, and targetted.

Season of Docs ideas for QGIS include the following:

  • Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.
  • Review the structure of current documentation and provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? A writer could assist with by defining the best practice structure.
  • Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so let's reduce the contributor’s barrier to entry by making this section so accurate and clear that anyone can pick it up.
  • Triage and then manage QGIS documentation issue tracker. Audit the status of QGIS documentation. Publicly share status, strategy, and vision which will help volunteers know how to engage, and what impact they can provide.
  • There are a number of geospatial training courses which cover a range of topics. Merging all these courses into a central source is not logical or desirable. However, there would be value in consolidating the geospatial and QGIS basics into a central base. This will be challenging, but valuable, and would require both excellent writing and coordination skills. Some of the content authors are already committed to sharing and supporting such an initiative. Others will likely come on board once momentum grows.

Resources:


On Sun, 21 Apr 2019 at 08:22, Cameron Shorter <[hidden email]> wrote:

Hi folks,

I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

Ideas I'm considering based on the conversations so far:

* There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

* OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

* "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

* The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

* QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

* With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

* Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

* I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

----

Please respond to this email with your ideas. I'll really appreciate the help.

What follows are the emails and ideas I've based the above thoughts upon.

Warm regards, Cameron

----


Matteo's suggestions:

  • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
  • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
  • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
  • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
Hi,

I agree with Jo's respone to Camerons question. 

Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

Regards

Andrew

On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
HI All,

<snip>

Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

Regards

Jo

On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

Warm regards, Cameron


On 10/4/19 10:13 pm, Nick Bearman wrote:
<snip>

I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254


--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254




_______________________________________________
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] [SeasonOfDocs] QGIS writing tasks need help

DelazJ
Hi Cameron and all,

I did not actively follow the discussion nor fully understand how the GSOD program will be organized, what actually can a senior technical writer provide as expertise but I'm already glad to see the interest of the wider OSGeo community in improving and learning from QGIS doc. It's nice to read comments from others than the Core QGIS writers or issue reporters. I don't know whether what I will raise below can be handled by the program and did not take the time to structure my thoughts (sorry) but I'd like to share things we do or want to do, and hear from other projects how they do.

Cameron, I share the points you compiled below, and thanks to all of you for your contributions.
I'd simply have expected that the step by step chapter is now accessible to beginners. We made an in-depth review few months ago, with (I may be wrong) the help of a writer and a "beginner". But still if you don't have enough potential contributors to test the process and tell you where they struggle to step in, it's hard for advanced contributors to find the right level to lower the barrier. That doesn't mean that what we did is perfect; if there's a way to improve and someone can help, it's more than welcome. Nick, for reference, last year Alexandre Neto made a video for first contribution to docs [0]; we should have added to the guidelines but forgot. It may need some cleanup but could maybe help you in your plan.

We, at QGIS, but I guess it's the same for all our projects, are lacking writers. Even call for paid writers failed in the past. I don't know whether a senior writer can help us understand why and find how to fix it but, it could be nice...

I've been contributing to QGIS doc for years and one thing I miss is a cap, a direction. What are the priorities? So I just adress "what I want, when I can". Or when I catch some requests on the mailing lists. Might not be different for others, I think. Until recently, we had a contributor asking what she should first focus on and no clear answer arose so yes, if someone can help us to get a strategy of writing, I'd be glad. And also define schedules, plan when releases should be better done. We do it greatly IMHO with the application, it could be nice to have the same for docs release. Experience from other projects may help here.

One of the strengths of QGIS Docs is the tightness we are building with the devs. For example, most of the dialogs (should) have a help button that opens online the feature page in the corresponding language of the user manual if available. In the future, the docs would be available locally.
Also, Most of our 400 issue reports are automatically generated by commits in QGIS code so we directly have what we should write about in the doc repo. But this becomes a weakness when:
- there's not enough people to write (increasing number of issues),
- there's no cleanup for duplicate issues (because of backports) or unrelated issues (eg API matters) --- we try to fix these ones
- or the commit message is not clear enough for writers (who may not have the same technical knowledge as the developer). If we can get some clues on how to make devs write more detailed description in noob language, big +1

I think that triaging the issue tracker and setting priorities and deadlines may greatly help in telling where a senior writer can help (in writing, I mean). I'm not sure any of us (at least me, I do not) have the actual big picture of the issue reports and can categorize them. We already have the necessary tags but now we need to use them. So this would be my task 1.

As Richard or Matteo mentioned, we are also reviewing the global formatting/rendering of the docs. Whether we move to readthedocs. In the meantime, we think it could be nice to improve the rendering of the Processing algorithms docs [1], looking for something more compact and easy to read. An initial work is done [2] and if we can get more help to finish the prototype and apply it could be nice.

Another issue we can have is that most of us are not English native speakers. So a review of the docs from an English speaker is more than desired. But I'm not sure if for this, we necessarily need the person to be a senior writer.

The training materials (dataset and instructions) are also an important item. We are still working on updating to QGIS 3 and I'm happy if there's a demand (/an offer?) to structure and join efforts on this area. But to be honest, I'm more interested in translatable docs (because I'm not in an English working environment and "my" community wouldn't reuse it otherwise) than building an English only infrastructure. So it could be nice if we keep the translatability (?) in mind. Maybe, another topic.

Sorry for the lengthy message. I hope there are information that clarify what we do, that you can pick and improve our submission. But whatever the result for GSOD, I think there are a lot of ideas in this thread we should try to implement in the long run.

[0] https://github.com/qgis/QGIS/wiki/20th-Developer-Meeting-in-Madeira,-February-2018#making-your-first-pull-request-to-qgis-documentation
[1] eg https://docs.qgis.org/3.4/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html
[2] https://github.com/qgis/QGIS-Documentation/pull/2770

PS: Since people were asking, the best way to contact the QGIS Doc team is to use the dedicated list [hidden email] as mentioned at https://www.qgis.org/en/site/getinvolved/mailinglists.html#qgis-community-team

Regards,
Harrissou Sant-anna


Le 22 avril 2019 15:03:35 GMT+02:00, Cameron Shorter <[hidden email]> a écrit :
I've updated the QGIS Season of Docs ideas, based on ideas on this list so far. Thanks for your ideas, especially thanks to Andrew for writing it out so clearly.

QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. QGIS core documentation is comprehensive and there is a diverse ecosystem of organisations and people who have created QGIS workshops and training courses. However, it is challenging for documenters to keep up with QGIS’s rapid innovation, to sustainably keep the breadth of documentation current, consistent, and targetted.

Season of Docs ideas for QGIS include the following:

  • Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.
  • Review the structure of current documentation and provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? A writer could assist with by defining the best practice structure.
  • Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so let's reduce the contributor’s barrier to entry by making this section so accurate and clear that anyone can pick it up.
  • Triage and then manage QGIS documentation issue tracker. Audit the status of QGIS documentation. Publicly share status, strategy, and vision which will help volunteers know how to engage, and what impact they can provide.
  • There are a number of geospatial training courses which cover a range of topics. Merging all these courses into a central source is not logical or desirable. However, there would be value in consolidating the geospatial and QGIS basics into a central base. This will be challenging, but valuable, and would require both excellent writing and coordination skills. Some of the content authors are already committed to sharing and supporting such an initiative. Others will likely come on board once momentum grows.

Resources:


On Sun, 21 Apr 2019 at 08:22, Cameron Shorter <[hidden email]> wrote:

Hi folks,

I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

Ideas I'm considering based on the conversations so far:

* There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

* OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

* "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

* The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

* QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

* With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

* Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

* I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

----

Please respond to this email with your ideas. I'll really appreciate the help.

What follows are the emails and ideas I've based the above thoughts upon.

Warm regards, Cameron

----


Matteo's suggestions:

  • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
  • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
  • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
  • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
Hi,

I agree with Jo's respone to Camerons question. 

Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

Regards

Andrew

On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
HI All,

<snip>

Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

Regards

Jo

On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

Warm regards, Cameron


On 10/4/19 10:13 pm, Nick Bearman wrote:
<snip>

I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254


--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254




--
Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.
_______________________________________________
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] [SeasonOfDocs] QGIS writing tasks need help

Bethel Ugochukwu Ukazu
Dear Colleagues, 

i have tried to provide some thoughts in text of Harrissou's email  (i beg your grace and indulgence to do this). 

if for any reason my contributions are out of place , i mean does not follow the discussion. please pardon me, i may have missed out due to many emails i receive from the group.

regards 

Bethel 


On Tuesday, April 23, 2019, 2:44:04 p.m. GMT+1, Harrissou <[hidden email]> wrote:


Hi Cameron and all,

I did not actively follow the discussion nor fully understand how the GSOD program will be organized, what actually can a senior technical writer provide as expertise but I'm already glad to see the interest of the wider OSGeo community in improving and learning from QGIS doc. It's nice to read comments from others than the Core QGIS writers or issue reporters. I don't know whether what I will raise below can be handled by the program and did not take the time to structure my thoughts (sorry) but I'd like to share things we do or want to do, and hear from other projects how they do.


Cameron, I share the points you compiled below, and thanks to all of you for your contributions.
I'd simply have expected that the step by step chapter is now accessible to beginners. We made an in-depth review few months ago, with (I may be wrong) the help of a writer and a "beginner". But still if you don't have enough potential contributors to test the process and tell you where they struggle to step in, it's hard for advanced contributors to find the right level to lower the barrier. That doesn't mean that what we did is perfect; if there's a way to improve and someone can help, it's more than welcome. Nick, for reference, last year Alexandre Neto made a video for first contribution to docs [0]; we should have added to the guidelines but forgot. It may need some cleanup but could maybe help you in your plan.



We, at QGIS, but I guess it's the same for all our projects, are lacking writers. Even call for paid writers failed in the past. I don't know whether a senior writer can help us understand why and find how to fix it but, it could be nice...

I've been contributing to QGIS doc for years and one thing I miss is a cap, a direction. What are the priorities? So I just adress "what I want, when I can". Or when I catch some requests on the mailing lists. Might not be different for others, I think. Until recently, we had a contributor asking what she should first focus on and no clear answer arose so yes, if someone can help us to get a strategy of writing, I'd be glad. And also define schedules, plan when releases should be better done. We do it greatly IMHO with the application, it could be nice to have the same for docs release. Experience from other projects may help here.

yes, i agree with this strategy or long term plan, lets say 2 year plan. i read emails always from the group , often times discussions on what to do are Brownian in nature, many times about what one thinks or feels. i may be wrong in my submission, but sincerely, it gets me to wonder if what the direction is for the group and what needs to be achieved.  
At the Level which QGIS is now, structure and institutional framework is expedient, urgent and not to be compromised at this time, if limitless boundaries and impossibilities is the goal for this generation Qgisers.

i understand the concepts of volunteers and interests around QGIS, but their needs to be a visionary leadership or lets say a kind of structure may be a cohort that gathers all our ideas together and fashion out clearly where we must go, how and when . 

Richard, Cameron, Matteo, Harry + some others, could take the lead in this initiative of putting up a SMART strategy 

An online meetings could be a start point to put these ideas together. But first  the 4+ of you may have to put like a first draft where others could build on. 

please not that this would be done without compromising the volunteer, individual responsibility nature of Qgisers


One of the strengths of QGIS Docs is the tightness we are building with the devs. For example, most of the dialogs (should) have a help button that opens online the feature page in the corresponding language of the user manual if available. In the future, the docs would be available locally. 

i agree with you on this 

Also, Most of our 400 issue reports are automatically generated by commits in QGIS code so we directly have what we should write about in the doc repo. But this becomes a weakness when:
- there's not enough people to write (increasing number of issues),
- there's no cleanup for duplicate issues (because of backports) or unrelated issues (eg API matters) --- we try to fix these ones
- or the commit message is not clear enough for writers (who may not have the same technical knowledge as the developer). If we can get some clues on how to make devs write more detailed description in noob language, big +1

I think that triaging the issue tracker and setting priorities and deadlines may greatly help in telling where a senior writer can help (in writing, I mean). I'm not sure any of us (at least me, I do not) have the actual big picture of the issue reports and can categorize them. We already have the necessary tags but now we need to use them. So this would be my task 1.

truly  , the big picture is missing and there is need to create one. 

As Richard or Matteo mentioned, we are also reviewing the global formatting/rendering of the docs. Whether we move to readthedocs. In the meantime, we think it could be nice to improve the rendering of the Processing algorithms docs [1], looking for something more compact and easy to read. An initial work is done [2] and if we can get more help to finish the prototype and apply it could be nice.

Another issue we can have is that most of us are not English native speakers. So a review of the docs from an English speaker is more than desired. But I'm not sure if for this, we necessarily need the person to be a senior writer.

how about having interns to do this work, may be for some of us who are researchers or working in organisations, on topics related to the ones raised here. May be there is a chance. 
should we have a structure, it would be easy to appreciate fellows who may support in working on these stuff. For example , a simple thank you letter with signatures of colleagues on this group may go a long way.....hahhahahah..... quite ambitions, i guess Emoji ....

The training materials (dataset and instructions) are also an important item. We are still working on updating to QGIS 3 and I'm happy if there's a demand (/an offer?) to structure and join efforts on this area. But to be honest, I'm more interested in translatable docs (because I'm not in an English working environment and "my" community wouldn't reuse it otherwise) than building an English only infrastructure. So it could be nice if we keep the translatability (?) in mind. Maybe, another topic.

Sorry for the lengthy message. I hope there are information that clarify what we do, that you can pick and improve our submission. But whatever the result for GSOD, I think there are a lot of ideas in this thread we should try to implement in the long run.

i am wondering,  if there is some form of documentation for ideas that come out of discussions in this group. i think its important to have these transitions and evolutionary processes documented.  A few years from now, there may be need to refer back to these, may be for posterity Emoji
which goes back to my submission for some form of structure. 


[0] https://github.com/qgis/QGIS/wiki/20th-Developer-Meeting-in-Madeira,-February-2018#making-your-first-pull-request-to-qgis-documentation
[1] eg https://docs.qgis.org/3.4/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html
[2] https://github.com/qgis/QGIS-Documentation/pull/2770

PS: Since people were asking, the best way to contact the QGIS Doc team is to use the dedicated list [hidden email] as mentioned at https://www.qgis.org/en/site/getinvolved/mailinglists.html#qgis-community-team

Regards,
Harrissou Sant-anna


Le 22 avril 2019 15:03:35 GMT+02:00, Cameron Shorter <[hidden email]> a écrit :
I've updated the QGIS Season of Docs ideas, based on ideas on this list so far. Thanks for your ideas, especially thanks to Andrew for writing it out so clearly.

QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. QGIS core documentation is comprehensive and there is a diverse ecosystem of organisations and people who have created QGIS workshops and training courses. However, it is challenging for documenters to keep up with QGIS’s rapid innovation, to sustainably keep the breadth of documentation current, consistent, and targetted.

Season of Docs ideas for QGIS include the following:

  • Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.
  • Review the structure of current documentation and provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? A writer could assist with by defining the best practice structure.
  • Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so let's reduce the contributor’s barrier to entry by making this section so accurate and clear that anyone can pick it up.
  • Triage and then manage QGIS documentation issue tracker. Audit the status of QGIS documentation. Publicly share status, strategy, and vision which will help volunteers know how to engage, and what impact they can provide.
  • There are a number of geospatial training courses which cover a range of topics. Merging all these courses into a central source is not logical or desirable. However, there would be value in consolidating the geospatial and QGIS basics into a central base. This will be challenging, but valuable, and would require both excellent writing and coordination skills. Some of the content authors are already committed to sharing and supporting such an initiative. Others will likely come on board once momentum grows.

Resources:


On Sun, 21 Apr 2019 at 08:22, Cameron Shorter <[hidden email]> wrote:

Hi folks,

I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

Ideas I'm considering based on the conversations so far:

* There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

* OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

* "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

* The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

* QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

* With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

* Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

* I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

----

Please respond to this email with your ideas. I'll really appreciate the help.

What follows are the emails and ideas I've based the above thoughts upon.

Warm regards, Cameron

----


    Matteo's suggestions:

    • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
    • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
    • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
    • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
    On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
    Hi,

    I agree with Jo's respone to Camerons question. 

    Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

    As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

    Regards

    Andrew

    On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
    HI All,

    <snip>

    Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

    Regards

    Jo

    On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

    Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

    I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

    It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

    What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

    Warm regards, Cameron


    On 10/4/19 10:13 pm, Nick Bearman wrote:
    <snip>

    I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

    I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

    -- 
    Cameron Shorter
    Technology Demystifier
    Open Technologies and Geospatial Consultant
    
    M +61 (0) 419 142 254


    --
    Cameron Shorter
    Technology Demystifier
    Open Technologies and Geospatial Consultant

    M +61 (0) 419 142 254




    --
    Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.
    _______________________________________________
    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] [SeasonOfDocs] QGIS writing tasks need help

    Cameron Shorter
    Hi Bethel and Harrissou,
    Thank you for sharing your insights into the QGIS community. This is really helpful feedback, and I'll update our Ideas page within the next day or two to incorporate some of your suggestions. The challenges you are facing and suggested solutions are eerily similar to those described within our OSGeoLive and GeoNetwork communities. So I think we are well positioned to focus on cross-project strategies.

    I suggest that you both join our OSGeo SeasonOfDocs email list, where we will be discussing these topics in more depth. (That offer extends to anyone else lurking on this list and interested to monitor progress or take part.) https://lists.osgeo.org/mailman/listinfo/seasonofdocs

    If you would like to continue contributing to the initiative, maybe as a writer, or mentor, or domain expert, then please also add your name to our "List of People Keen to be Involved":


    On Wed, 24 Apr 2019 at 03:32, Bethel Ugochukwu Ukazu <[hidden email]> wrote:
    Dear Colleagues, 

    i have tried to provide some thoughts in text of Harrissou's email  (i beg your grace and indulgence to do this). 

    if for any reason my contributions are out of place , i mean does not follow the discussion. please pardon me, i may have missed out due to many emails i receive from the group.

    regards 

    Bethel 


    On Tuesday, April 23, 2019, 2:44:04 p.m. GMT+1, Harrissou <[hidden email]> wrote:


    Hi Cameron and all,

    I did not actively follow the discussion nor fully understand how the GSOD program will be organized, what actually can a senior technical writer provide as expertise but I'm already glad to see the interest of the wider OSGeo community in improving and learning from QGIS doc. It's nice to read comments from others than the Core QGIS writers or issue reporters. I don't know whether what I will raise below can be handled by the program and did not take the time to structure my thoughts (sorry) but I'd like to share things we do or want to do, and hear from other projects how they do.


    Cameron, I share the points you compiled below, and thanks to all of you for your contributions.
    I'd simply have expected that the step by step chapter is now accessible to beginners. We made an in-depth review few months ago, with (I may be wrong) the help of a writer and a "beginner". But still if you don't have enough potential contributors to test the process and tell you where they struggle to step in, it's hard for advanced contributors to find the right level to lower the barrier. That doesn't mean that what we did is perfect; if there's a way to improve and someone can help, it's more than welcome. Nick, for reference, last year Alexandre Neto made a video for first contribution to docs [0]; we should have added to the guidelines but forgot. It may need some cleanup but could maybe help you in your plan.



    We, at QGIS, but I guess it's the same for all our projects, are lacking writers. Even call for paid writers failed in the past. I don't know whether a senior writer can help us understand why and find how to fix it but, it could be nice...

    I've been contributing to QGIS doc for years and one thing I miss is a cap, a direction. What are the priorities? So I just adress "what I want, when I can". Or when I catch some requests on the mailing lists. Might not be different for others, I think. Until recently, we had a contributor asking what she should first focus on and no clear answer arose so yes, if someone can help us to get a strategy of writing, I'd be glad. And also define schedules, plan when releases should be better done. We do it greatly IMHO with the application, it could be nice to have the same for docs release. Experience from other projects may help here.

    yes, i agree with this strategy or long term plan, lets say 2 year plan. i read emails always from the group , often times discussions on what to do are Brownian in nature, many times about what one thinks or feels. i may be wrong in my submission, but sincerely, it gets me to wonder if what the direction is for the group and what needs to be achieved.  
    At the Level which QGIS is now, structure and institutional framework is expedient, urgent and not to be compromised at this time, if limitless boundaries and impossibilities is the goal for this generation Qgisers.

    i understand the concepts of volunteers and interests around QGIS, but their needs to be a visionary leadership or lets say a kind of structure may be a cohort that gathers all our ideas together and fashion out clearly where we must go, how and when . 

    Richard, Cameron, Matteo, Harry + some others, could take the lead in this initiative of putting up a SMART strategy 

    An online meetings could be a start point to put these ideas together. But first  the 4+ of you may have to put like a first draft where others could build on. 

    please not that this would be done without compromising the volunteer, individual responsibility nature of Qgisers


    One of the strengths of QGIS Docs is the tightness we are building with the devs. For example, most of the dialogs (should) have a help button that opens online the feature page in the corresponding language of the user manual if available. In the future, the docs would be available locally. 

    i agree with you on this 

    Also, Most of our 400 issue reports are automatically generated by commits in QGIS code so we directly have what we should write about in the doc repo. But this becomes a weakness when:
    - there's not enough people to write (increasing number of issues),
    - there's no cleanup for duplicate issues (because of backports) or unrelated issues (eg API matters) --- we try to fix these ones
    - or the commit message is not clear enough for writers (who may not have the same technical knowledge as the developer). If we can get some clues on how to make devs write more detailed description in noob language, big +1

    I think that triaging the issue tracker and setting priorities and deadlines may greatly help in telling where a senior writer can help (in writing, I mean). I'm not sure any of us (at least me, I do not) have the actual big picture of the issue reports and can categorize them. We already have the necessary tags but now we need to use them. So this would be my task 1.

    truly  , the big picture is missing and there is need to create one. 

    As Richard or Matteo mentioned, we are also reviewing the global formatting/rendering of the docs. Whether we move to readthedocs. In the meantime, we think it could be nice to improve the rendering of the Processing algorithms docs [1], looking for something more compact and easy to read. An initial work is done [2] and if we can get more help to finish the prototype and apply it could be nice.

    Another issue we can have is that most of us are not English native speakers. So a review of the docs from an English speaker is more than desired. But I'm not sure if for this, we necessarily need the person to be a senior writer.

    how about having interns to do this work, may be for some of us who are researchers or working in organisations, on topics related to the ones raised here. May be there is a chance. 
    should we have a structure, it would be easy to appreciate fellows who may support in working on these stuff. For example , a simple thank you letter with signatures of colleagues on this group may go a long way.....hahhahahah..... quite ambitions, i guess Emoji ....

    The training materials (dataset and instructions) are also an important item. We are still working on updating to QGIS 3 and I'm happy if there's a demand (/an offer?) to structure and join efforts on this area. But to be honest, I'm more interested in translatable docs (because I'm not in an English working environment and "my" community wouldn't reuse it otherwise) than building an English only infrastructure. So it could be nice if we keep the translatability (?) in mind. Maybe, another topic.

    Sorry for the lengthy message. I hope there are information that clarify what we do, that you can pick and improve our submission. But whatever the result for GSOD, I think there are a lot of ideas in this thread we should try to implement in the long run.

    i am wondering,  if there is some form of documentation for ideas that come out of discussions in this group. i think its important to have these transitions and evolutionary processes documented.  A few years from now, there may be need to refer back to these, may be for posterity Emoji
    which goes back to my submission for some form of structure. 


    [0] https://github.com/qgis/QGIS/wiki/20th-Developer-Meeting-in-Madeira,-February-2018#making-your-first-pull-request-to-qgis-documentation
    [1] eg https://docs.qgis.org/3.4/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html
    [2] https://github.com/qgis/QGIS-Documentation/pull/2770

    PS: Since people were asking, the best way to contact the QGIS Doc team is to use the dedicated list [hidden email] as mentioned at https://www.qgis.org/en/site/getinvolved/mailinglists.html#qgis-community-team

    Regards,
    Harrissou Sant-anna


    Le 22 avril 2019 15:03:35 GMT+02:00, Cameron Shorter <[hidden email]> a écrit :
    I've updated the QGIS Season of Docs ideas, based on ideas on this list so far. Thanks for your ideas, especially thanks to Andrew for writing it out so clearly.

    QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. QGIS core documentation is comprehensive and there is a diverse ecosystem of organisations and people who have created QGIS workshops and training courses. However, it is challenging for documenters to keep up with QGIS’s rapid innovation, to sustainably keep the breadth of documentation current, consistent, and targetted.

    Season of Docs ideas for QGIS include the following:

    • Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.
    • Review the structure of current documentation and provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? A writer could assist with by defining the best practice structure.
    • Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so let's reduce the contributor’s barrier to entry by making this section so accurate and clear that anyone can pick it up.
    • Triage and then manage QGIS documentation issue tracker. Audit the status of QGIS documentation. Publicly share status, strategy, and vision which will help volunteers know how to engage, and what impact they can provide.
    • There are a number of geospatial training courses which cover a range of topics. Merging all these courses into a central source is not logical or desirable. However, there would be value in consolidating the geospatial and QGIS basics into a central base. This will be challenging, but valuable, and would require both excellent writing and coordination skills. Some of the content authors are already committed to sharing and supporting such an initiative. Others will likely come on board once momentum grows.

    Resources:


    On Sun, 21 Apr 2019 at 08:22, Cameron Shorter <[hidden email]> wrote:

    Hi folks,

    I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

    https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

    I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

    We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

    Ideas I'm considering based on the conversations so far:

    * There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

    * OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

    * "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

    * The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

    * QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

    * With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

    * Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

    * I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

    ----

    Please respond to this email with your ideas. I'll really appreciate the help.

    What follows are the emails and ideas I've based the above thoughts upon.

    Warm regards, Cameron

    ----


      Matteo's suggestions:

      • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
      • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
      • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
      • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
      On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
      Hi,

      I agree with Jo's respone to Camerons question. 

      Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

      As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

      Regards

      Andrew

      On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
      HI All,

      <snip>

      Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

      Regards

      Jo

      On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

      Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

      I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

      It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

      What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

      Warm regards, Cameron


      On 10/4/19 10:13 pm, Nick Bearman wrote:
      <snip>

      I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

      I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

      -- 
      Cameron Shorter
      Technology Demystifier
      Open Technologies and Geospatial Consultant
      
      M +61 (0) 419 142 254


      --
      Cameron Shorter
      Technology Demystifier
      Open Technologies and Geospatial Consultant

      M +61 (0) 419 142 254




      --
      Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.
      _______________________________________________
      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


      --
      Cameron Shorter
      Technology Demystifier
      Open Technologies and Geospatial Consultant

      M +61 (0) 419 142 254




      _______________________________________________
      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] [SeasonOfDocs] QGIS writing tasks need help

      Cameron Shorter

      I've updated the QGIS task descriptions, based on suggestions from Harrissou and Bethel. Thanks. I've also provided a cross section of perspectives on the state of QGIS by linking back to some of your emails in the Resources section.

      https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS


      On 24/4/19 8:22 am, Cameron Shorter wrote:
      Hi Bethel and Harrissou,
      Thank you for sharing your insights into the QGIS community. This is really helpful feedback, and I'll update our Ideas page within the next day or two to incorporate some of your suggestions. The challenges you are facing and suggested solutions are eerily similar to those described within our OSGeoLive and GeoNetwork communities. So I think we are well positioned to focus on cross-project strategies.

      I suggest that you both join our OSGeo SeasonOfDocs email list, where we will be discussing these topics in more depth. (That offer extends to anyone else lurking on this list and interested to monitor progress or take part.) https://lists.osgeo.org/mailman/listinfo/seasonofdocs

      If you would like to continue contributing to the initiative, maybe as a writer, or mentor, or domain expert, then please also add your name to our "List of People Keen to be Involved":


      On Wed, 24 Apr 2019 at 03:32, Bethel Ugochukwu Ukazu <[hidden email]> wrote:
      Dear Colleagues, 

      i have tried to provide some thoughts in text of Harrissou's email  (i beg your grace and indulgence to do this). 

      if for any reason my contributions are out of place , i mean does not follow the discussion. please pardon me, i may have missed out due to many emails i receive from the group.

      regards 

      Bethel 


      On Tuesday, April 23, 2019, 2:44:04 p.m. GMT+1, Harrissou <[hidden email]> wrote:


      Hi Cameron and all,

      I did not actively follow the discussion nor fully understand how the GSOD program will be organized, what actually can a senior technical writer provide as expertise but I'm already glad to see the interest of the wider OSGeo community in improving and learning from QGIS doc. It's nice to read comments from others than the Core QGIS writers or issue reporters. I don't know whether what I will raise below can be handled by the program and did not take the time to structure my thoughts (sorry) but I'd like to share things we do or want to do, and hear from other projects how they do.


      Cameron, I share the points you compiled below, and thanks to all of you for your contributions.
      I'd simply have expected that the step by step chapter is now accessible to beginners. We made an in-depth review few months ago, with (I may be wrong) the help of a writer and a "beginner". But still if you don't have enough potential contributors to test the process and tell you where they struggle to step in, it's hard for advanced contributors to find the right level to lower the barrier. That doesn't mean that what we did is perfect; if there's a way to improve and someone can help, it's more than welcome. Nick, for reference, last year Alexandre Neto made a video for first contribution to docs [0]; we should have added to the guidelines but forgot. It may need some cleanup but could maybe help you in your plan.



      We, at QGIS, but I guess it's the same for all our projects, are lacking writers. Even call for paid writers failed in the past. I don't know whether a senior writer can help us understand why and find how to fix it but, it could be nice...

      I've been contributing to QGIS doc for years and one thing I miss is a cap, a direction. What are the priorities? So I just adress "what I want, when I can". Or when I catch some requests on the mailing lists. Might not be different for others, I think. Until recently, we had a contributor asking what she should first focus on and no clear answer arose so yes, if someone can help us to get a strategy of writing, I'd be glad. And also define schedules, plan when releases should be better done. We do it greatly IMHO with the application, it could be nice to have the same for docs release. Experience from other projects may help here.

      yes, i agree with this strategy or long term plan, lets say 2 year plan. i read emails always from the group , often times discussions on what to do are Brownian in nature, many times about what one thinks or feels. i may be wrong in my submission, but sincerely, it gets me to wonder if what the direction is for the group and what needs to be achieved.  
      At the Level which QGIS is now, structure and institutional framework is expedient, urgent and not to be compromised at this time, if limitless boundaries and impossibilities is the goal for this generation Qgisers.

      i understand the concepts of volunteers and interests around QGIS, but their needs to be a visionary leadership or lets say a kind of structure may be a cohort that gathers all our ideas together and fashion out clearly where we must go, how and when . 

      Richard, Cameron, Matteo, Harry + some others, could take the lead in this initiative of putting up a SMART strategy 

      An online meetings could be a start point to put these ideas together. But first  the 4+ of you may have to put like a first draft where others could build on. 

      please not that this would be done without compromising the volunteer, individual responsibility nature of Qgisers


      One of the strengths of QGIS Docs is the tightness we are building with the devs. For example, most of the dialogs (should) have a help button that opens online the feature page in the corresponding language of the user manual if available. In the future, the docs would be available locally. 

      i agree with you on this 

      Also, Most of our 400 issue reports are automatically generated by commits in QGIS code so we directly have what we should write about in the doc repo. But this becomes a weakness when:
      - there's not enough people to write (increasing number of issues),
      - there's no cleanup for duplicate issues (because of backports) or unrelated issues (eg API matters) --- we try to fix these ones
      - or the commit message is not clear enough for writers (who may not have the same technical knowledge as the developer). If we can get some clues on how to make devs write more detailed description in noob language, big +1

      I think that triaging the issue tracker and setting priorities and deadlines may greatly help in telling where a senior writer can help (in writing, I mean). I'm not sure any of us (at least me, I do not) have the actual big picture of the issue reports and can categorize them. We already have the necessary tags but now we need to use them. So this would be my task 1.

      truly  , the big picture is missing and there is need to create one. 

      As Richard or Matteo mentioned, we are also reviewing the global formatting/rendering of the docs. Whether we move to readthedocs. In the meantime, we think it could be nice to improve the rendering of the Processing algorithms docs [1], looking for something more compact and easy to read. An initial work is done [2] and if we can get more help to finish the prototype and apply it could be nice.

      Another issue we can have is that most of us are not English native speakers. So a review of the docs from an English speaker is more than desired. But I'm not sure if for this, we necessarily need the person to be a senior writer.

      how about having interns to do this work, may be for some of us who are researchers or working in organisations, on topics related to the ones raised here. May be there is a chance. 
      should we have a structure, it would be easy to appreciate fellows who may support in working on these stuff. For example , a simple thank you letter with signatures of colleagues on this group may go a long way.....hahhahahah..... quite ambitions, i guess Emoji ....

      The training materials (dataset and instructions) are also an important item. We are still working on updating to QGIS 3 and I'm happy if there's a demand (/an offer?) to structure and join efforts on this area. But to be honest, I'm more interested in translatable docs (because I'm not in an English working environment and "my" community wouldn't reuse it otherwise) than building an English only infrastructure. So it could be nice if we keep the translatability (?) in mind. Maybe, another topic.

      Sorry for the lengthy message. I hope there are information that clarify what we do, that you can pick and improve our submission. But whatever the result for GSOD, I think there are a lot of ideas in this thread we should try to implement in the long run.

      i am wondering,  if there is some form of documentation for ideas that come out of discussions in this group. i think its important to have these transitions and evolutionary processes documented.  A few years from now, there may be need to refer back to these, may be for posterity Emoji
      which goes back to my submission for some form of structure. 


      [0] https://github.com/qgis/QGIS/wiki/20th-Developer-Meeting-in-Madeira,-February-2018#making-your-first-pull-request-to-qgis-documentation
      [1] eg https://docs.qgis.org/3.4/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html
      [2] https://github.com/qgis/QGIS-Documentation/pull/2770

      PS: Since people were asking, the best way to contact the QGIS Doc team is to use the dedicated list [hidden email] as mentioned at https://www.qgis.org/en/site/getinvolved/mailinglists.html#qgis-community-team

      Regards,
      Harrissou Sant-anna


      Le 22 avril 2019 15:03:35 GMT+02:00, Cameron Shorter <[hidden email]> a écrit :
      I've updated the QGIS Season of Docs ideas, based on ideas on this list so far. Thanks for your ideas, especially thanks to Andrew for writing it out so clearly.

      QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. QGIS core documentation is comprehensive and there is a diverse ecosystem of organisations and people who have created QGIS workshops and training courses. However, it is challenging for documenters to keep up with QGIS’s rapid innovation, to sustainably keep the breadth of documentation current, consistent, and targetted.

      Season of Docs ideas for QGIS include the following:

      • Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.
      • Review the structure of current documentation and provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? A writer could assist with by defining the best practice structure.
      • Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so let's reduce the contributor’s barrier to entry by making this section so accurate and clear that anyone can pick it up.
      • Triage and then manage QGIS documentation issue tracker. Audit the status of QGIS documentation. Publicly share status, strategy, and vision which will help volunteers know how to engage, and what impact they can provide.
      • There are a number of geospatial training courses which cover a range of topics. Merging all these courses into a central source is not logical or desirable. However, there would be value in consolidating the geospatial and QGIS basics into a central base. This will be challenging, but valuable, and would require both excellent writing and coordination skills. Some of the content authors are already committed to sharing and supporting such an initiative. Others will likely come on board once momentum grows.

      Resources:


      On Sun, 21 Apr 2019 at 08:22, Cameron Shorter <[hidden email]> wrote:

      Hi folks,

      I'm struggling to compile QGIS writing tasks for SeasonOfDocs which are as compelling as Jo and Maria have put together for GeoNetwork:

      https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork

      I'm hoping that those of you who have used QGIS docs can list strengths and then be fully transparent about its weaknesses. If we don't have much of a problem, something requiring senior technical writer expertise, then why would Google want to help us? There will be plenty of worthy projects for Google to select from.

      We have 3 days (till 23 April) to respond. Could you please help by brainstorming ideas in this email thread. I'll commit to compiling them into https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . (Although feel free to update it yourself.)

      Ideas I'm considering based on the conversations so far:

      * There appears to be a high technical barrier to entry which makes it hard for new users to engage with improving QGIS docs. Is this so? What writing tasks could we put in place to address this?

      * OSGeoLive has successfully attracted authors from ~ 50 projects to write Quickstarts and Project Overviews based on clear templates and writing guides. Would a template/writing guide be useful for QGIS? For what doc types? Workshops? Tutorials? (I'm suspecting these to be in the sweet spot for us, as they could be rolled out through OSGeoLive to other projects).

      * "Training materials are generally tailored to a customer, their technical use case, using sample maps from the customer's location in the world. This makes it difficult to develop consolidated material that works for everyone". However, "there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area." How can we define this task more clearly?

      * The GeoNetwork team have provided an honest statement about the quality and completeness of their documentation. Does QGIS documentation have similar limitations? (My initial skim over docs suggest that the quality might be better, but I could be wrong.)

      * QGIS has had a major feature update from 2.18 to 3.4.x. I suspect we should talk about this? What documentation still needs to be updated or improved as a consequence?

      * With a rapidly innovating product like QGIS, with large documentation base, we could be running into challenges around maintenance and sustainability. Do you consider this a problem? If so, can you provide examples we can reference? Do you have suggestions on writing tasks to address this?

      * Matteo mentions an issue tracker with over 400 writing tasks in it. How do we resource the management of these issues? We likely won't be allocated a senior writer to action such a list (Google's target for this initiative), but we might get a junior writer. This might not be supported until future Google writing initiatives, based on our identified need for such a role.

      * I'm aware that there are multiple QGIS training courses on the web, some which are free and open. Could you identify those that a tech writer should consider. You can list in the "Resources:" list in https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS . I notice that much of the training on the web is still based on version 2.18. Should we suggest effort be dedicated to updating them to 3.4?

      ----

      Please respond to this email with your ideas. I'll really appreciate the help.

      What follows are the emails and ideas I've based the above thoughts upon.

      Warm regards, Cameron

      ----


      Matteo's suggestions:

      • Pyqgis cookbook code snipped are now automatically tested, meaning that every new contribution will be rock solid and code snippets can be taken "as they are" and pasted in QGIS
      • Change the doc style to the more readable Read-The-Docs vanilla theme (fully supported by sphinx). A live example here https://qgis.org/test/en/.
      • Besides from contents, writing documentation isn't easy because of the complex framework (sphinx, git, github, etc). Improving the WYSIWYG github editor would be a great enhancement
      • Cleaning the issue tracker in github (> 400 issue now) in many different ways: verifying issues, closing duplicates, make order in the labels, etc
      On 12/4/19 2:46 pm, Andrew Jeffrey wrote:
      Hi,

      I agree with Jo's respone to Camerons question. 

      Training materials are generally tailored to a type of customer and I this believe makes it difficult to develop consolidated material that works for everyone. The similarities I do see in training material though is the basics, the kind of basics that are taught to new users like those in the education space.

      As Jo mentioned there is potential here to break a monolopy in this space, and get exposure to new users early in their development. What makes this even better is a solid training material base owned by the community can be used by anyone creating training material, providing a consistent training base whether you learn in your own time online or go to trainer "A". Effectively consolidating the "QGIS beginner" training material.

      Regards

      Andrew

      On Thu, Apr 11, 2019 at 2:21 AM Jo Cook <[hidden email]> wrote:
      HI All,

      <snip>

      Secondly- Cameron's question about QGIS courses- we also run QGIS training courses in the UK, and I think there's a fairly wide market, both geographically, and in the types of customer. We are focused on integration with cloud technologies, such as delivering QGIS via AWS AppStream, and less on teaching people to use all of the functionality, for example for higher-end processing and analysis. Having said that, I think there's a really big need for standard training materials- and also if possible the kind of training materials that could be used for schools, to try to break the monopoly that certain proprietary companies have on that area.

      Regards

      Jo

      On Wed, Apr 10, 2019 at 2:27 PM Cameron Shorter <[hidden email]> wrote:

      Thanks for the introduction Nick. One thing that puzzles me is that there appears to be a lot of people setting up QGIS training courses and I would have thought it would be beneficial of these separate initiatives were to become more consolidated.

      I'd expect that consolidating workshops would be a very valuable task, as it would focus the community together.

      It would also be a suitably challenging task to bring multiple threads together, and something that would be worthy of a senior technical writer's expertise.

      What are people's thoughts on the current state of available QGIS training courses? Is there potential to consolidate? Or is everyone tailoring to their unique user base?

      Warm regards, Cameron


      On 10/4/19 10:13 pm, Nick Bearman wrote:
      <snip>

      I'm keen to learn how to contribute more effectively, particularly to QGIS documentation, and I am also looking to run a workshop on how to contribute to OS documentation at upcoming FOSS4G UK event in Edinburgh, UK in Sept.

      I am familiar with Git/GitHub and Markdown. The RST format of the QGIS Documentation site sometimes eludes me! I look forward to working with you all. 

      -- 
      Cameron Shorter
      Technology Demystifier
      Open Technologies and Geospatial Consultant
      
      M +61 (0) 419 142 254


      --
      Cameron Shorter
      Technology Demystifier
      Open Technologies and Geospatial Consultant

      M +61 (0) 419 142 254




      --
      Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.
      _______________________________________________
      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


      --
      Cameron Shorter
      Technology Demystifier
      Open Technologies and Geospatial Consultant

      M +61 (0) 419 142 254



      -- 
      Cameron Shorter
      Technology Demystifier
      Open Technologies and Geospatial Consultant
      
      M +61 (0) 419 142 254

      _______________________________________________
      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