<div dir="ltr"><div>Hi all,</div><div><br></div><div>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:</div><div><br></div><div><a href="https://docs.qgis.org/3.4/en/docs/documentation_guidelines/" target="_blank">https://docs.qgis.org/3.4/en/docs/documentation_guidelines/</a></div><div><br></div><div>and I recently started to create some videos on how to edit <br></div><div><br></div><div>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:</div><div><br></div><div>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.<br></div><div><br></div><div>There should still be space for volunteers contributions, but a project like QGIS can no longer rely on it only.<br></div><div><br></div><div>Alex Neto</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Aug 27, 2019 at 1:42 PM Cameron Shorter <<a href="mailto:cameron.shorter@gmail.com" target="_blank">cameron.shorter@gmail.com</a>> wrote:<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>
<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>
<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_4887893270829262395gmail-m_4184431766752097628moz-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>
<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.</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>
<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>
<p>Cheers, Cameron<br>
</p>
<div class="gmail-m_4887893270829262395gmail-m_4184431766752097628moz-cite-prefix">On 26/8/19 11:15 pm, matteo wrote:<br>
</div>
<blockquote type="cite">
<pre class="gmail-m_4887893270829262395gmail-m_4184431766752097628moz-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_4887893270829262395gmail-m_4184431766752097628moz-cite-prefix">On 27/8/19 5:14 pm,
<a class="gmail-m_4887893270829262395gmail-m_4184431766752097628moz-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_4887893270829262395gmail-m_4184431766752097628moz-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_4887893270829262395gmail-m_4184431766752097628moz-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_4887893270829262395gmail-m_4184431766752097628gmail-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_4887893270829262395gmail-m_4184431766752097628gmail-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_4887893270829262395gmail-m_4184431766752097628moz-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>