[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
    herehttps://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 <jo.k.cook at gmail.com 
> <mailto:jo.k.cook at gmail.com>> 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
>     <cameron.shorter at gmail.com <mailto:cameron.shorter at gmail.com>> 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20190421/9f35bc3b/attachment.html>