[Qgis-community-team] Draft paper discussing QGIS docs

[Cameron Shorter]

Andreas, Matteo, Anita, Rosa, Régis,

Some great and tough questions and suggestions here.

I'm won't have the bandwidth this week to answer all questions to the 
depth I'd like, but I'll touch on a few highlights.

I think we should start with clearly defining a vision for what we would 
like QGIS docs to look like. Without that, it is hard to do a gap 
analysis and quantify what is missing. If people can't easily see the 
problem, they are less likely to volunteer to fix it.

This vision should cover the doc set we will create, the level of 
quality we expect, the target audience who will be satisfied, and how 
they will be satisfied, the maintenance and currency and probably a few 
other things.

I think we should clearly and very publicly define what we consider to 
be highly valuable contributions (like working on core docs) vs 
disconnected docs which are only available for a select few. Maybe this 
could be embedded into a "doc pledge" which we can invite organisations 
to sign up to. This will help sponsors to recognise, prioritise and fund 
high quality initiatives.

I think QGIS docs would benefit hugely from someone directly dedicated 
to a "community builder" type role. You will typically see at least one 
and sometimes a few of these people at the center of successful open 
source projects. They typically go beyond the call of duty to help all 
sorts of people work through all sorts of challenges. They do whatever 
dirty work is required, such as triaging issues and building releases, 
but also reach out to people, invite them to help out, follow up with 
them later, simplify and fix processes and so on. Note, the primary 
focus of this role is empowering others to be productive, and attracting 
others and being nice, empathetic and encouraging. It is also about 
saying "no, we don't have bandwidth to do that for you". I see elements 
of this within the QGIS docs list, but I've the feeling that QGIS has 
become too big for this to be sustained on volunteer labour alone. It 
would be great if this could be funded as a full time role. I'd suggest 
that a community builder's role be modeled on some great research into 
attracting and sustaining volunteers, which I've summarised here: 
http://cameronshorter.blogspot.com/2018/12/catching-elusive-episodic-volunteer.html 


We keep seeing training courses created and not given back to the QGIS 
core. For this I think we need to target the business case of people 
putting on courses. Firstly, educate users about which courses the QGIS 
community likes (namely ones which integrate and contribute to QGIS 
docs). It is good business to go where students are being sent.  Then 
lets help make it easy to bring material back into our core material. It 
is expensive to integrate your personal course with external material. 
This is something that a "community builder" could really help with and 
spend time on, especially with the first couple of course(s) we bring 
in. As above, define to Universities what we expect of them to be good 
open source citizens. And help course writers to write a business case 
to collaborate. (Info at: 
http://cameronshorter.blogspot.com/2018/10/the-open-business-business-case.html 
)

I really think that we can reduce the barrier to entry for QGIS docs 
people. For OSGeoLive, we went from hardly attracting contributors to 
attracting scores of volunteers by modularising and making it easy to 
contribute, along with asking, and following up. QGIS will be harder to 
move, but I'm convinced it is achievable following a similar formula. In 
particular, we can help techies become good writers by having a senior 
tech writer offer to review the docs written (in line with templates we 
plan to build with TheGoodDocsProject. Initially this reviewer might be 
the community builder, but it could become a separate role.
OSGeoLive story here: 
http://cameronshorter.blogspot.com/2011/06/memoirs-of-cat-herder-coordinating.html

I'd have the "community builder" lead the breaking of tasks and docs 
into sections, then reaching out to groups people and inspiring them to 
take on a task or two.

I'd also suggest setting up periodic meetings, probably weekly. These 
are really good for keeping the momentum going and inspiring each other.

Rosa, re videos: Yes, they are great for users. They are also very time 
consuming to maintain and update with each release. Be careful to ensure 
that you only create as much material as your team have the capacity to 
sustainably maintain.

Re giving awards: I've been researching quite a bit into motivational 
theory, which taps into gamification theory. It talks about intrinsic 
motivation vs extrinsic motivation. Why Open Source volunteers so often 
sustain valuable contributions for so long is they are intrinsically 
motivated - for a greater purpose and higher goal. Acknowledging 
someone's good work is worth doing, but handing out gold stars for 
effort has the potential sometimes to cheapen the person's contribution 
- as it can be tapping into extrinsic motivation, which is less sustained.

Cheers, Cameron

On 26/8/19 11:15 pm, matteo wrote:
> Hi Cameron,
>
> thanks for the doc that summarized the ideas we discussed last week.
>
> The QGIS-Documentation repository if seen as a "standalone" projects is
> a huge container to coordinate. Here are some of my thoughts, I'd love
> to have feedback on this:
>
> * we have a complex framework (we all know that!). But IMHO, this
> complexity is fundamental for the project. Even if we are behind the
> code, the quality of the documented features is awesome.
> * this complex framework has a steep learning curve and I think we
> cannot do anything here rather than explain the guidelines as we did
> (maybe enhancing them with other example, but complex will stay)
> * we cannot have "spot" contributors (e.g. who wants to add a small
> chapter of specialized use) because of this (only exception is an
> already skilled person)
> * we have a growing issue cue (>500)
> * even if many improvements have been done (automatic screenshots,
> pyqgis tests), sometimes these tools make the whole framework more
> complex (sigh!)
>
>
> I totally agree with Andreas: there are plenty resources outside and
> just a few of them are included in the core (not judging the choice just
> seeing what is happening). Same for some new features documented in
> personal company websites and not directly in core (with a badge like:
> Feature developed by MyCompany).
>
>
> Here some early proposals:
>
> * having more of "us" core contributors dedicated to specific tasks
> (guy1 -> mainly review, guy2 -> help desk, guy3 -> css and graphic, guy4
> -> IT framework, guy5 -> issue chief..)
> * giving some "awards" for people that wants to add a something in core
> rather than on personal website ??
> * having a specified workflow for PR: review 1, style and content ->
> review 2, native English speaker -> merge
>
> The challenge we should win is to attract more people that can
> contribute continuously to the project
>
> Hoping to start a nice discussion
On 27/8/19 5:14 pm, r.m.aguilardearchila at utwente.nl wrote:
>
> Dear all,
>
> I would like to share my humble opinion in this topic.
>
> I think that a quick way to illustrate QGIS functionality could be via 
> videos.
>
> I have seen how videos can complement an user guide or tutorial.
>
> What I propose is:
>
> For end users, design a workflow (written/diagram) and add a short 
> video of the how-to.  Recording screens can be faster than deciding 
> the right sentence, e.g., the exact semantic.
>
> I think that perhaps this approach can speed the documentation 
> process. This could seem a naïve suggestion from a beginner 
> user/documenter but big companies are doing so.
>
> Cheers
>
> Rosa
>
On 26/8/19 11:10 pm, Andreas Neumann wrote:
>
> Hi Régis,
>
> Thanks for your thoughts.
>
> I hope I did not give the impression that I dislike that people are 
> blogging about new QGIS features on their own personal blogs or 
> company websites. This was not my intention.
>
> But I wonder what prevents those people companies from ALSO 
> contributing this valuable information, next to their own personal 
> websites, to QGIS.ORG? Is the process or are the tools too 
> complicated? I mean - if you spend 1-2 days about preparing and 
> writing on your own blog post. Why not also spending the extra 1-2 
> hours for copy/pasting this same information also to the centralized 
> QGIS.ORG documentation?
>
> I think there is really nothing wrong about building up personal 
> reputation. I think it is a good thing and one of the main drivers 
> behind Open Source.
>
> But it would be good if the QGIS.ORG could also benefit from this 
> tremendous work these people do.
>
> Awards are maybe a good idea to honor the work of such people or 
> mentions in annual reports, at conferences, etc.
>
> Greetings,
> Andreas
>
> Am 26.08.19 um 16:02 schrieb Régis Haubourg:
>> Hi all,
>> just a quick reaction to that long standing issue,
>>
>> Le lun. 26 août 2019 à 14:42, Andreas Neumann <a.neumann at carto.net 
>> <mailto:a.neumann at carto.net>> a écrit :
>>
>>     Hi again,
>>
>>     Another observation I have is that there is an awful lot of
>>     documentation about QGIS out their on the web, spread into many
>>     personal blog websites, company blog posts and news sites,
>>     youtube movies, social media posts, etc. etc. However, all of
>>     this vast and de-centralized information doesn't end up in our
>>     central documentation.
>>
>> Agreed!
>>
>>     My assumption is that people prefer to add such information more
>>     to their own, personal website, rather than to QGIS.OR because it
>>     helps them to:
>>
>>       * build personal reputation (individual persons). I think about
>>         people like Anita Graser, Klas Karlsson, and probably many
>>         others who always add the new cool stuff to their own
>>         websites, but not to QGIS.ORG <http://QGIS.ORG>
>>
>> Agreed, myself included at a small scale
>>
>>      *
>>
>>
>>       * show off what cool features the company added recently to
>>         QGIS core (which helps their business) - examples are
>>         companies like OpenGIS, Oslandia, etc. who add new cool stuff
>>         to their company website, but not to QGIS.ORG <http://QGIS.ORG>
>>
>> Well, concerning Oslandia, we have been trying to systematically 
>> document in the doc the newly created features, and blog posts are a 
>> complement. We might have missed some, but that's the idea. In fact, 
>> not all customers accept the very high costs of the full quality 
>> package "feature + review + doc" . We've already been discussing this 
>> on the list some times and I remember opinions are mixed here. 
>> Personaly, I would vote for making minimal doc PR along with the 
>> feature PR the default behavior, with possible exemptions.  (hum, 
>> make me think that we merged a PR this morning without documenting 
>> it, let's do that )
>>
>>
>>       * better  learn and understand how QGIS works (which is useful
>>         for building up their skills). I heard from Harrissou that
>>         this was his main motivation to contribute to the centralized
>>         QGIS documentation.
>>
>>     From these above three different motivations, only the last one
>>     can be fulfilled by adding new information to our centralized
>>     documentation, the other two are better done outside of the
>>     centralized documentation.
>>
>>     So I wonder if the huge work of documentors in the centralized
>>     documentation could be better credited/attributed to individuals,
>>     so that the other two motivations of gaining personal or company
>>     reputation by contributing to the centralized QGIS documentation
>>     is better fulfilled?
>>
>> Not an easy task, but we at last have github statistics. Maybe 
>> blogging each year about QGIS project status, and mentionning the 
>> special efforts made by active contributors during the past year. Why 
>> not going towards some kind of reward, just like OSGEO has the 
>> Sol-Katz ? Just random thoughts too.
>>
>>     Just some thoughts ...
>>
>>     Andreas
>>
>>     Am 26.08.19 um 15:10 schrieb Andreas Neumann:
>>>     Hi Cameron,
>>>
>>>     Thank you for summarizing your observations and assessment on
>>>     the current state of documentation in QGIS.
>>>
>>>     I agree that the documentation task seems to be overwhelming and
>>>     might also be daunting for newcomers, volunteers and even paid
>>>     people. I also agree that the team is under-resourced.
>>>
>>>     However, we already knew this before your assessment.
>>>
>>>     So I wonder if you could add your thoughts and recommendations
>>>     on how to improve our situation? We already know about our
>>>     misery and bad state, but it would be encouraging to hear more
>>>     suggestions for how to improve the situation. This would be
>>>     really valuable for us.
>>>
>>>     It is not primarily a problem of finding financial resources.
>>>     Every year we assigned funds for documentation and in most years
>>>     those funds haven't been used. Even if we would make more funds
>>>     available to the team, I feel this wouldn't solve the problems
>>>     the team is facing.
>>>
>>>     Should the team focus on smaller chunks/goals in order to have
>>>     better progress and a better success feeling?
>>>
>>>     Are the tools to complicated?
>>>
>>>     Is there not enough information provided by developers or
>>>     organizations who fund a new features?
>>>
>>>     Thanks again for adding more suggestions and advice to your
>>>     document - this would help us much more than just the assessment
>>>     of the current state.
>>>
>>>     Andreas
>>>
>>>     Am 26.08.19 um 14:35 schrieb Cameron Shorter:
>>>>     For those involved in QGIS docs,
>>>>
>>>>     After a bit of brainstorming with Matteo about what next for
>>>>     QGIS docs, I offered to put some ideas down into an article to
>>>>     give him something tangible to take to the QGIS Project
>>>>     Steering Committee next week.
>>>>
>>>>     I feel my thoughts have room to be developed a bit and I'd be
>>>>     keen to hear feedback on them before I copy to my blog at the
>>>>     end of this week.
>>>>
>>>>     https://docs.google.com/document/d/11N5d1aBgkdQ80I7RKBlt_jx9Uk1RGsvOTeq_TSFeljA/edit#
>>>>
>>>>
>>>>     Comments are preferred to track changes (which become hard to
>>>>     manage). If you comment, please log in first so I know who said
>>>>     what.
>>>>
-- 
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/20190827/9414efda/attachment-0001.html>