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

[Cameron Shorter]

Hi Regis, some good ideas in here, I'll comment inline

On 28/8/19 12:00 am, Régis Haubourg wrote:
> Hi Cameron,
>
> Le mar. 27 août 2019 à 14:42, Cameron Shorter 
> <cameron.shorter at gmail.com <mailto:cameron.shorter at gmail.com>> a écrit :
>
>     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.
>
> To me, the final and ideal goal would be :
> - each released version should be associated with an english version 
> within 2 months after the release
> - Each LTR version should have fully translated version when it is 
> tagged as LTR
> - New features should be easy to document and not be a technical debt 
> from developpers to documentation team.
> - Training material should be updated for LTR, and tested, within 6 
> months after the LTR release. I don't think being faster is any useful 
> given the delay in actual migrations and large scale trainings
> - Fixing an error in doc or translation should be doable only with web 
> interface and quickly, so that trainers can fix issues during their 
> training sessions.
This is a good start on a vision.
>
>     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 this was one the goals of the certification program. Shortly 
> said, you want to deliver certificates and be yourself a certifying 
> organisation. You need to be a regular contributor, and thus a member 
> of the community. There are many ways to contribute of course, not 
> only documentation.
>
>     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
>
>
> Much agreed. This leads us to progressively secure those that 
> contribute so much by paying them for this. The more ressources we 
> have, the more we'll be able to fund those low level tasks (don't 
> forget communication, code review, packaging etc.. in those critical 
> functions. I think this was a second goal of the certification 
> program. As it already raised 10 000 euros with only 500 certificates 
> delivered, and given that very few of us started to sell them, this 
> makes me optimistic about having enough ressources in a close future 
> to secure such roles.

10 000 euros doesn't sound like much to me.

Think about how much each of you could earn if working as a contractor 
today.

How much documentation work is required for each technical feature 
coded? Maybe 30% of the coding effort to document the API. Maybe over 
200% if you additionally consider updating videos, training courses, and 
translations as well.

>     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.
>
> Well, I think that on this part the documentation team is doing great 
> coordination and leadership. I think, they ask for more manpower mainly.
>
>     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.
>
> True, but I think they tend to become the mainstream information 
> channel for young generations.  I'm +1 to test it. Go Alexander ! ;)
>
>     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.
>
> This is really intersecting to have in mind when starting to 
> contribute. Contributor burn out is a concern, especially on those 
> moment with so much users relying on us, and not so much ressources or 
> new comers jumping in.  Knowing yourself, understanding why you are 
> starting to contribute is in my opinion really important (I just 
> experienced it recently on myself, so I'm especially keen that we find 
> sustainable ways )

-- 
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/20190828/e4edde80/attachment-0001.html>