<div dir="ltr"><div dir="ltr">Hi Cameron,<br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Le mar. 27 août 2019 à 14:42, Cameron Shorter <<a href="mailto:cameron.shorter@gmail.com">cameron.shorter@gmail.com</a>> a écrit :<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF">
<p>Andreas, Matteo, Anita, Rosa, Régis,</p>
<p>Some great and tough questions and suggestions here.</p>
<p>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.</p>
<p>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.</p></div></blockquote><div>To me, the final and ideal goal would be :</div><div>- each released version should be associated with an english version within 2 months after the release</div><div>- Each LTR version should have fully translated version when it is tagged as LTR</div><div>- New features should be easy to document and not be a technical debt from developpers to documentation team. <br></div><div>- 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</div><div>- 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. <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF">
<p>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.</p>
<p>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.</p></div></blockquote><div>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. <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF">
<p>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:
<a class="gmail-m_-8963796712721259496moz-txt-link-freetext" href="http://cameronshorter.blogspot.com/2018/12/catching-elusive-episodic-volunteer.html" target="_blank">http://cameronshorter.blogspot.com/2018/12/catching-elusive-episodic-volunteer.html</a>
<br></p></div></blockquote><div>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. <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p>
</p>
<p>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: <a href="http://cameronshorter.blogspot.com/2018/10/the-open-business-business-case.html" target="_blank">http://cameronshorter.blogspot.com/2018/10/the-open-business-business-case.html</a>
)<br>
</p>
<p>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.<br>
OSGeoLive story here: <a href="http://cameronshorter.blogspot.com/2011/06/memoirs-of-cat-herder-coordinating.html" target="_blank">http://cameronshorter.blogspot.com/2011/06/memoirs-of-cat-herder-coordinating.html</a></p>
<p>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.</p>
<p>I'd also suggest setting up periodic meetings, probably weekly.
These are really good for keeping the momentum going and inspiring
each other.<br><br></p></div></blockquote><div>Well, I think that on this part the documentation team is doing great coordination and leadership. I think, they ask for more manpower mainly. <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p></p>
<p>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.<br></p></div></blockquote><div>True, but I think they tend to become the mainstream information channel for young generations. I'm +1 to test it. Go Alexander ! ;) <br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF"><p>
</p>
<p> 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.</p></div></blockquote><div>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 )</div><div><br></div><div>Regards, <br></div><div>Régis<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div bgcolor="#FFFFFF">
<p>Cheers, Cameron<br>
</p>
<div class="gmail-m_-8963796712721259496moz-cite-prefix">On 26/8/19 11:15 pm, matteo wrote:<br>
</div>
<blockquote type="cite">
<pre class="gmail-m_-8963796712721259496moz-quote-pre">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</pre>
</blockquote>
<div class="gmail-m_-8963796712721259496moz-cite-prefix">On 27/8/19 5:14 pm,
<a class="gmail-m_-8963796712721259496moz-txt-link-abbreviated" href="mailto:r.m.aguilardearchila@utwente.nl" target="_blank">r.m.aguilardearchila@utwente.nl</a> wrote:<br>
</div>
<blockquote type="cite">
<p class="MsoNormal"><span style="color:windowtext">Dear all,</span></p>
<p class="MsoNormal"><span style="color:windowtext">I would
like to share my humble opinion in this topic.
</span></p>
<p class="MsoNormal"><span style="color:windowtext">I think
that a quick way to illustrate QGIS functionality could be via
videos.
</span></p>
<p class="MsoNormal"><span style="color:windowtext">I have
seen how videos can complement an user guide or tutorial.</span></p>
<p class="MsoNormal"><span style="color:windowtext">What I
propose is:
</span></p>
<p class="MsoNormal"><span style="color:windowtext">
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.</span></p>
<p class="MsoNormal"><span style="color:windowtext">
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.</span></p>
<p class="MsoNormal"><span style="color:windowtext">Cheers</span></p>
<p class="MsoNormal"><span style="color:windowtext">Rosa</span></p>
</blockquote>
<div class="gmail-m_-8963796712721259496moz-cite-prefix">On 26/8/19 11:10 pm, Andreas Neumann
wrote:<br>
</div>
<blockquote type="cite">
<p>Hi Régis,</p>
<p>Thanks for your thoughts.</p>
<p>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.</p>
<p>But I wonder what prevents those people companies from ALSO
contributing this valuable information, next to their own
personal websites, to <a href="http://QGIS.ORG" target="_blank">QGIS.ORG</a>? 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 <a href="http://QGIS.ORG" target="_blank">QGIS.ORG</a> documentation?</p>
<p>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.</p>
<p>But it would be good if the <a href="http://QGIS.ORG" target="_blank">QGIS.ORG</a> could also benefit from
this tremendous work these people do.</p>
<p>Awards are maybe a good idea to honor the work of such people
or mentions in annual reports, at conferences, etc.</p>
<p>Greetings,<br>
Andreas<br>
</p>
<div class="gmail-m_-8963796712721259496moz-cite-prefix">Am 26.08.19 um 16:02 schrieb Régis
Haubourg:<br>
</div>
<blockquote type="cite">
<div dir="ltr">
<div dir="ltr">
<div>Hi all, <br>
</div>
<div>just a quick reaction to that long standing issue,<br>
</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">Le lun. 26 août 2019
à 14:42, Andreas Neumann <<a href="mailto:a.neumann@carto.net" target="_blank">a.neumann@carto.net</a>>
a écrit :<br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF">
<p>Hi again,</p>
<p>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.<br>
</p>
</div>
</blockquote>
<div>Agreed! <br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF">
<p> </p>
<p>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:</p>
<ul>
<li>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 <a href="http://QGIS.ORG" target="_blank">QGIS.ORG</a></li>
</ul>
</div>
</blockquote>
<div>Agreed, myself included at a small scale <br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF">
<ul>
<li><br>
</li>
<li>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 <a href="http://QGIS.ORG" target="_blank">QGIS.ORG</a></li>
</ul>
</div>
</blockquote>
<div>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 ) <br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF"><br>
<ul>
<li>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.<br>
</li>
</ul>
<p>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.</p>
<p>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?</p>
</div>
</blockquote>
<div>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. <br>
</div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div bgcolor="#FFFFFF">
<p>Just some thoughts ...</p>
<p>Andreas<br>
</p>
<div class="gmail-m_-8963796712721259496gmail-m_8799709505958677171moz-cite-prefix">Am
26.08.19 um 15:10 schrieb Andreas Neumann:<br>
</div>
<blockquote type="cite">Hi Cameron, <br>
<br>
Thank you for summarizing your observations and
assessment on the current state of documentation in
QGIS. <br>
<br>
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. <br>
<br>
However, we already knew this before your assessment.
<br>
<br>
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. <br>
<br>
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. <br>
<br>
Should the team focus on smaller chunks/goals in order
to have better progress and a better success feeling?
<br>
<br>
Are the tools to complicated? <br>
<br>
Is there not enough information provided by developers
or organizations who fund a new features? <br>
<br>
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. <br>
<br>
Andreas <br>
<br>
Am 26.08.19 um 14:35 schrieb Cameron Shorter: <br>
<blockquote type="cite">For those involved in QGIS
docs, <br>
<br>
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. <br>
<br>
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. <br>
<br>
<a class="gmail-m_-8963796712721259496gmail-m_8799709505958677171moz-txt-link-freetext" href="https://docs.google.com/document/d/11N5d1aBgkdQ80I7RKBlt_jx9Uk1RGsvOTeq_TSFeljA/edit#" target="_blank">https://docs.google.com/document/d/11N5d1aBgkdQ80I7RKBlt_jx9Uk1RGsvOTeq_TSFeljA/edit#</a>
<br>
<br>
Comments are preferred to track changes (which
become hard to manage). If you comment, please log
in first so I know who said what. <br>
<br>
</blockquote>
</blockquote>
</div>
</blockquote>
</div>
</div>
</blockquote>
</blockquote>
<pre class="gmail-m_-8963796712721259496moz-signature" cols="72">--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant
M +61 (0) 419 142 254</pre>
</div>
_______________________________________________<br>
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..<br>
<a href="mailto:Qgis-community-team@lists.osgeo.org" target="_blank">Qgis-community-team@lists.osgeo.org</a><br>
<a href="https://lists.osgeo.org/mailman/listinfo/qgis-community-team" rel="noreferrer" target="_blank">https://lists.osgeo.org/mailman/listinfo/qgis-community-team</a></blockquote></div></div>