[SeasonOfDocs] [Qgis-community-team] QGIS writing tasks need help
Cameron Shorter
cameron.shorter at gmail.com
Sun Apr 21 06:25:19 PDT 2019
Richard,
I think you might have missed a subtle difference between Season Of Docs
and Summer Of Code.
* Summer Of Code targets JUNIOR developers.
* Season Of Docs targets SENIOR writers.
Senior writers could typically be tasked with structuring documentation
to simplify navigation and target different learning styles, or
explaining difficult concepts clearly and concisely.
From your list, a senior writer could review the Training Manual and
the Gentle Introduction (and others) to see how best to structure.
With regards to extra features needing documenting that you mention. Are
you able to quantify the current status of this? What percentage of
features have docs / have docs that need updating / have no docs?
Andrew, thanks for sharing your metrics from first time users. Your
suggested tasks are well defined, which would make them easier to hand
over to a technical writer for implementation. I'll be interested to
hear feedback from others on this.
On 21/4/19 8:50 pm, Richard š Duivenvoorde wrote:
> Hi Cameron,
>
> In my opinion we have a rather good process (but therefor for newcomers
> complex?) of writing the docs.
>
> Our weakspots:
>
> - writing rst in 'QGIS doc style' is not trivial (in my opinion): adding
> images is well, tricky, the different kind of 'substitutions' to use,
> the building process, git handling, keeping images uptodate (we have
> been busy with machinery to do this automagically) etc etc.
> Not sure if this is something to be picked up by juniors though.
> I thought about having a process like: juniors create images + text and
> others integrate it in the Docs. BUT... tried that last month: received
> a Word Doc with good docs about Mesh Layers, and thought to wedge that
> into rst... took me a lot of time ... too much... so this 2-step writing
> is not what I would prefer now.
>
> Some wild ideas:
> - because of all the information, it is hard to keep 'overview', if we
> could find something for that?
> - About Andrew's note about people asking how to do the 'easy things'
> like opening datasets: I sometimes think we humans want things to
> happen too easy: having complex data or crs's it is hard to make it
> 'easy'. We have a Training Manual and a Gentle Introduction... Maybe
> these could be 'merged' in one uptodate one? (others: is that doable?).
> Or add a better 'how to add data into QGIS chapter in (one of) those'?
> - we have been talking about updating the build process to have a zip of
> the docs IN QGIS for offline use (but this is not a writer task)..
>
> But we have a huge list of new features which can be used to write docs
> for in 'bite sized parts':
> https://github.com/qgis/QGIS-Documentation/issues
>
> But again: it is for junior writers (or QGIS users) maybe hard to find
> WHAT exactly to write, it is even hard for experienced writers often...
>
> So maybe (my) conclusion is that we do not have that much 'low hanging'
> fruit?
> Others?
>
> Regards,
>
> Richard Duivenvoorde
>
> ps: what about a 'doc team heads up again'?
>
> On 21/04/2019 06.10, Andrew Jeffrey 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
>> 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
>>> <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
>>
>>
>> _______________________________________________
>> Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
>> Qgis-community-team at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
>>
--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant
M +61 (0) 419 142 254
More information about the SeasonOfDocs
mailing list