[SeasonOfDocs] QGIS writing tasks need help
Cameron Shorter
cameron.shorter at gmail.com
Sat Apr 20 15:22:26 PDT 2019
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/seasonofdocs/attachments/20190421/9f35bc3b/attachment.html>
More information about the SeasonOfDocs
mailing list