[Qgis-community-team] [SeasonOfDocs] QGIS writing tasks need help

Cameron Shorter cameron.shorter at gmail.com
Wed Apr 24 19:29:07 PDT 2019


I've updated the QGIS task descriptions, based on suggestions from 
Harrissou and Bethel. Thanks. I've also provided a cross section of 
perspectives on the state of QGIS by linking back to some of your emails 
in the Resources section.

https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS


On 24/4/19 8:22 am, Cameron Shorter wrote:
> Hi Bethel and Harrissou,
> Thank you for sharing your insights into the QGIS community. This is 
> really helpful feedback, and I'll update our Ideas page within the 
> next day or two to incorporate some of your suggestions. The 
> challenges you are facing and suggested solutions are eerily similar 
> to those described within our OSGeoLive and GeoNetwork communities. So 
> I think we are well positioned to focus on cross-project strategies.
>
> I suggest that you both join our OSGeo SeasonOfDocs email list, where 
> we will be discussing these topics in more depth. (That offer extends 
> to anyone else lurking on this list and interested to monitor progress 
> or take part.) https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> If you would like to continue contributing to the initiative, maybe as 
> a writer, or mentor, or domain expert, then please also add your name 
> to our "List of People Keen to be Involved":
>
> https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#Key_roles_sought
>
> On Wed, 24 Apr 2019 at 03:32, Bethel Ugochukwu Ukazu 
> <ugobethu21 at yahoo.com <mailto:ugobethu21 at yahoo.com>> wrote:
>
>     Dear Colleagues,
>
>     i have tried to provide some thoughts in text of Harrissou's
>     email  (i beg your grace and indulgence to do this).
>
>     if for any reason my contributions are out of place , i mean does
>     not follow the discussion. please pardon me, i may have missed out
>     due to many emails i receive from the group.
>
>     regards
>
>     Bethel
>
>
>     On Tuesday, April 23, 2019, 2:44:04 p.m. GMT+1, Harrissou
>     <delazj at gmail.com <mailto:delazj at gmail.com>> wrote:
>
>
>     Hi Cameron and all,
>
>     I did not actively follow the discussion nor fully understand how
>     the GSOD program will be organized, what actually can a senior
>     technical writer provide as expertise but I'm already glad to see
>     the interest of the wider OSGeo community in improving and
>     learning from QGIS doc. It's nice to read comments from others
>     than the Core QGIS writers or issue reporters. I don't know
>     whether what I will raise below can be handled by the program and
>     did not take the time to structure my thoughts (sorry) but I'd
>     like to share things we do or want to do, and hear from other
>     projects how they do.
>
>
>     Cameron, I share the points you compiled below, and thanks to all
>     of you for your contributions.
>     I'd simply have expected that the step by step chapter is now
>     accessible to beginners. We made an in-depth review few months
>     ago, with (I may be wrong) the help of a writer and a "beginner".
>     But still if you don't have enough potential contributors to test
>     the process and tell you where they struggle to step in, it's hard
>     for advanced contributors to find the right level to lower the
>     barrier. That doesn't mean that what we did is perfect; if there's
>     a way to improve and someone can help, it's more than welcome.
>     Nick, for reference, last year Alexandre Neto made a video for
>     first contribution to docs [0]; we should have added to the
>     guidelines but forgot. It may need some cleanup but could maybe
>     help you in your plan.
>
>
>
>     We, at QGIS, but I guess it's the same for all our projects, are
>     lacking writers. Even call for paid writers failed in the past. I
>     don't know whether a senior writer can help us understand why and
>     find how to fix it but, it could be nice...
>
>     I've been contributing to QGIS doc for years and one thing I miss
>     is a cap, a direction. What are the priorities? So I just adress
>     "what I want, when I can". Or when I catch some requests on the
>     mailing lists. Might not be different for others, I think. Until
>     recently, we had a contributor asking what she should first focus
>     on and no clear answer arose so yes, if someone can help us to get
>     a strategy of writing, I'd be glad. And also define schedules,
>     plan when releases should be better done. We do it greatly IMHO
>     with the application, it could be nice to have the same for docs
>     release. Experience from other projects may help here.
>
>     yes, i agree with this strategy or long term plan, lets say 2 year
>     plan. i read emails always from the group , often times
>     discussions on what to do are Brownian in nature, many times about
>     what one thinks or feels. i may be wrong in my submission, but
>     sincerely, it gets me to wonder if what the direction is for the
>     group and what needs to be achieved.
>     At the Level which QGIS is now, structure and institutional
>     framework is expedient, urgent and not to be compromised at this
>     time, if limitless boundaries and impossibilities is the goal for
>     this generation Qgisers.
>
>     i understand the concepts of volunteers and interests around QGIS,
>     but their needs to be a visionary leadership or lets say a kind of
>     structure may be a cohort that gathers all our ideas together and
>     fashion out clearly where we must go, how and when .
>
>     Richard, Cameron, Matteo, Harry + some others, could take the lead
>     in this initiative of putting up a SMART strategy
>
>     An online meetings could be a start point to put these ideas
>     together. But first  the 4+ of you may have to put like a first
>     draft where others could build on.
>
>     please not that this would be done without compromising the
>     volunteer, individual responsibility nature of Qgisers
>
>
>     One of the strengths of QGIS Docs is the tightness we are building
>     with the devs. For example, most of the dialogs (should) have a
>     help button that opens online the feature page in the
>     corresponding language of the user manual if available. In the
>     future, the docs would be available locally.
>
>     i agree with you on this
>
>     Also, Most of our 400 issue reports are automatically generated by
>     commits in QGIS code so we directly have what we should write
>     about in the doc repo. But this becomes a weakness when:
>     - there's not enough people to write (increasing number of issues),
>     - there's no cleanup for duplicate issues (because of backports)
>     or unrelated issues (eg API matters) --- we try to fix these ones
>     - or the commit message is not clear enough for writers (who may
>     not have the same technical knowledge as the developer). If we can
>     get some clues on how to make devs write more detailed description
>     in noob language, big +1
>
>     I think that triaging the issue tracker and setting priorities and
>     deadlines may greatly help in telling where a senior writer can
>     help (in writing, I mean). I'm not sure any of us (at least me, I
>     do not) have the actual big picture of the issue reports and can
>     categorize them. We already have the necessary tags but now we
>     need to use them. So this would be my task 1.
>
>     truly , the big picture is missing and there is need to create one.
>
>     As Richard or Matteo mentioned, we are also reviewing the global
>     formatting/rendering of the docs. Whether we move to readthedocs.
>     In the meantime, we think it could be nice to improve the
>     rendering of the Processing algorithms docs [1], looking for
>     something more compact and easy to read. An initial work is done
>     [2] and if we can get more help to finish the prototype and apply
>     it could be nice.
>
>     Another issue we can have is that most of us are not English
>     native speakers. So a review of the docs from an English speaker
>     is more than desired. But I'm not sure if for this, we necessarily
>     need the person to be a senior writer.
>
>     how about having interns to do this work, may be for some of us
>     who are researchers or working in organisations, on topics related
>     to the ones raised here. May be there is a chance.
>     should we have a structure, it would be easy to appreciate fellows
>     who may support in working on these stuff. For example , a simple
>     thank you letter with signatures of colleagues on this group may
>     go a long way.....hahhahahah..... quite ambitions, i guess Emoji ....
>
>     The training materials (dataset and instructions) are also an
>     important item. We are still working on updating to QGIS 3 and I'm
>     happy if there's a demand (/an offer?) to structure and join
>     efforts on this area. But to be honest, I'm more interested in
>     translatable docs (because I'm not in an English working
>     environment and "my" community wouldn't reuse it otherwise) than
>     building an English only infrastructure. So it could be nice if we
>     keep the translatability (?) in mind. Maybe, another topic.
>
>     Sorry for the lengthy message. I hope there are information that
>     clarify what we do, that you can pick and improve our submission.
>     But whatever the result for GSOD, I think there are a lot of ideas
>     in this thread we should try to implement in the long run.
>
>     i am wondering,  if there is some form of documentation for ideas
>     that come out of discussions in this group. i think its important
>     to have these transitions and evolutionary processes documented. 
>     A few years from now, there may be need to refer back to these,
>     may be for posterity Emoji.
>     which goes back to my submission for some form of structure.
>
>
>     [0]
>     https://github.com/qgis/QGIS/wiki/20th-Developer-Meeting-in-Madeira,-February-2018#making-your-first-pull-request-to-qgis-documentation
>     [1] eg
>     https://docs.qgis.org/3.4/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html
>     [2] https://github.com/qgis/QGIS-Documentation/pull/2770
>
>     PS: Since people were asking, the best way to contact the QGIS Doc
>     team is to use the dedicated list
>     qgis-community-team at lists.osgeo.org
>     <mailto:qgis-community-team at lists.osgeo.org> as mentioned at
>     https://www.qgis.org/en/site/getinvolved/mailinglists.html#qgis-community-team
>
>     Regards,
>     Harrissou Sant-anna
>
>
>     Le 22 avril 2019 15:03:35 GMT+02:00, Cameron Shorter
>     <cameron.shorter at gmail.com <mailto:cameron.shorter at gmail.com>> a
>     écrit :
>
>         I've updated the QGIS Season of Docs ideas, based on ideas on
>         this list so far. Thanks for your ideas, especially thanks to
>         Andrew for writing it out so clearly.
>
>         https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS
>
>         QGIS, a desktop GIS application, is one of the OSGeo
>         Foundation’s flagship projects with a broad developer and
>         documentation community. QGIS core documentation is
>         comprehensive and there is a diverse ecosystem of
>         organisations and people who have created QGIS workshops and
>         training courses. However, it is challenging for documenters
>         to keep up with QGIS’s rapid innovation, to sustainably keep
>         the breadth of documentation current, consistent, and targetted.
>
>         Season of Docs ideas for QGIS include the following:
>
>           * 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 the structure of current documentation and 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? A writer could assist with by defining 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 let's reduce the
>             contributor’s barrier to entry by making this section so
>             accurate and clear that anyone can pick it up.
>           * Triage and then manage QGIS documentation issue tracker.
>             Audit the status of QGIS documentation. Publicly share
>             status, strategy, and vision which will help volunteers
>             know how to engage, and what impact they can provide.
>           * There are a number of geospatial training courses which
>             cover a range of topics. Merging all these courses into a
>             central source is not logical or desirable. However, there
>             would be value in consolidating the geospatial and QGIS
>             basics into a central base. This will be challenging, but
>             valuable, and would require both excellent writing and
>             coordination skills. Some of the content authors are
>             already committed to sharing and supporting such an
>             initiative. Others will likely come on board once momentum
>             grows.
>
>         Resources:
>
>           * QGIS Documentation <https://www.qgis.org/en/docs/index.html>
>           * QGIS Documentation Issues
>             <https://github.com/qgis/QGIS-Documentation/issues>
>           * University-level lectures and labs, created by GeoAcademy
>             <http://spatialquerylab.com/foss4g-academy-curriculum/> (based
>             on the older QGIS 2.18)
>           * Environmental QGIS training and videos
>             <https://www.gaiaresources.com.au/qgis-vids/> from Gaia
>             Resources (based on the older QGIS 2.18)
>
>
>         On Sun, 21 Apr 2019 at 08:22, 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
>
>
>
>         -- 
>         Cameron Shorter
>         Technology Demystifier
>         Open Technologies and Geospatial Consultant
>
>         M +61 (0) 419 142 254
>
>
>
>
>     -- 
>     Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez
>     excuser ma brièveté.
>     _______________________________________________
>     Qgis-community-team mailing list for organizing community
>     resources such as documentation, translation etc..
>     Qgis-community-team at lists.osgeo.org
>     <mailto: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
>
>
>
-- 
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/qgis-community-team/attachments/20190425/ae627c17/attachment-0001.html>


More information about the Qgis-community-team mailing list