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

Tue Aug 27 07:21:35 PDT 2019

Hi all,

I think we have already identified a few limitations on QGIS Documentation
workflow a long time ago, but it's quite hard for us (QGIS Documentation
team) to move away from what we have without some kind of divine
intervention. In my opinion, the biggest challenge is to attract volunteer
people to it and keep them motivated to regularly contribute. A lot has
been discussed about lowering the barrier for new contributors but moving
away from git+sphinx is for me a "no-go". Why? Because we can't manage 400+
pages of content using google docs or any other WYSIWYG editor. We could
move to markdown instead of sphinx, but I don't think that would make
people contribute more. I think we already decided that, in terms of
infrastructure, we will need to keep using git and sphinx. So we need to
teach people how to use it. There is some good information here:

https://docs.qgis.org/3.4/en/docs/documentation_guidelines/

and I recently started to create some videos on how to edit

I don't understand what you mean by having a clear vision of what we want
our documentation to be. In my opinion, QGIS Documentation is quite good
(at least the user manual). Sure we could trim some fats here and there,
and determine what fits in the user manual, what should go to the training
manual. But maybe I am not seeing the full picture, maybe there are other
ways of organizing the documentation. But even if we do, we still just
don't have enough manpower to do it. We don't even have the manpower to
keep it updated! Facts are, we have 2/3 active persons working on
documentation "against" a couple of dozens of QGIS core developers. And
that leads me to a conclusion:

The same way we have moved most of QGIS development from volunteer
contributions to professional services done by individuals and companies,
the same must happen to documentation. IMHO, when a company (or its client)
fund a new feature, the documentation work should also be included. Once
the new feature is done and merged, the second half of the work should be
documenting it at least in the users manual.

There should still be space for volunteers contributions, but a project
like QGIS can no longer rely on it only.

Alex Neto

On Tue, Aug 27, 2019 at 1:42 PM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> 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> 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
>>
>> 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
>>
>> 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
>
> _______________________________________________
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20190827/9ddda970/attachment-0001.html>