[SeasonOfDocs] [Qgis-community-team] 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/seasonofdocs/attachments/20190425/ae627c17/attachment-0001.html>
More information about the SeasonOfDocs
mailing list