[SeasonOfDocs] QGIS writing tasks need help

Sat Apr 20 21:10:24 PDT 2019

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 <cameron.shorter at gmail.com>
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 <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> 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
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190421/f8ac8917/attachment.html>