[SeasonOfDocs] QGIS writing tasks need help

Sun Apr 21 03:23:05 PDT 2019

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 <aljeffrey83 at gmail.com> 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 <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
>>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>

-- 
Nick Bearman
01209 808910 | 07717745715
nick at geospatialtrainingsolutions.co.uk

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190421/7f9960c4/attachment-0001.html>