[SeasonOfDocs] QGIS writing tasks need help
Cameron Shorter
cameron.shorter at gmail.com
Sun Apr 21 06:35:13 PDT 2019
Richard, it seems from your last response that you hadn't read Nick's
email. Maybe you are not subscribed to seasonofdocs at lists.osgeo.org
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 <aljeffrey83 at gmail.com
> <mailto: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 <mailto: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
> 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
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
>
>
> --
> Nick Bearman
> 01209 808910 | 07717745715
> nick at geospatialtrainingsolutions.co.uk
> <mailto: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.
--
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/6ba006be/attachment-0001.html>
More information about the SeasonOfDocs
mailing list