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

[Cameron Shorter]

On 29/8/19 7:37 pm, DelazJ wrote:
> Hi,
>
> A lot has been said, there are topics within the topic and I would 
> like to reply to each that I couldn't.
> Thanks Cameron to raise (again) this issue we all know already. But 
> it's sometimes good to hear things from people outside (though you are 
> not really outside). As I said in the GDocs, imho it's unfortunate to 
> not assign a senior writer to QGIS. I was personally envisioning that 
> as a catalyzer, an opportunity to trigger mobilisation of the writing 
> community, and teach us actual and best practices. And maybe that 
> experience would confirm us that we need that profile you seem to 
> propose in later message. Anyways... we'll try to keep Jared around, 
> if he agrees of course.

Harrissou,

Yes, I understand the disappointment. It was a tough call for me to 
allocate the tech writers elsewhere. To further explain:

The Google Tech writer will only going to be available for 3 months. My 
read is that QGIS has big documentation challenges and the short 3 
months a tech writer can throw at the problem would have a likely impact 
of creating a doc plan, and then not have anyone volunteers to follow 
through on the plan. I felt it was a safer proposition to go with the 
GeoNetwork and OSGeoLive tasks.

--

I was discussing this QGIS doc challenges with Clarence, who is a senior 
tech writing helping with TheGoodDocsProject. He noted that there are 
lots of writers wanting to break into tech writing and not knowing where 
to start.

There is a slack jobs board within the WriteTheDocs community. He 
suggested that we draw up a job description, float it on the board, and 
we might get some people join us - maybe even as volunteers. We teach 
them how to use git and RST and open source processes and in return they 
teach us how to write.

An idea to add to our next steps list.

>
> Le jeu. 29 août 2019 à 08:24, Tim Sutton <tim at kartoza.com 
> <mailto:tim at kartoza.com>> a écrit :
>
>     Hi
>
>     I have a different opinion on this. Based on our experience of
>     paying developers I don’t think it has in any way reduced the
>     volunteer contributions to the code base - on the contrary it
>      probably has incentivised those that we paid to donate lots more
>     of their time. I am pretty sure that we will have similar
>     experience in other areas of the project. I am more bullish on
>     documentation and thank that we should work enthusiastically to
>     get one or more dedicated, full time document writers in the QGIS
>     project….over and over we here it is the most wanting part of the
>     project. The biggest problem we have is that we need a better
>     platform for authoring and managing the docs so that you dont
>     first need a degree in rocket science before you can participate :-P
>
We are discussing the git learning barrier in TheGoodDocsProject 
meetings, with tech writers.

While it is certainly a barrier, it need not be a barrier for a paid 
writer, or maybe even the volunteer we might find via above process. (If 
a techie volunteers to hand hold a writer through the process).


>
> As far as I can tell, all you need is a web browser and a github 
> account. It's enough to address some of the "Easy" tagged issues [0] 
> we identify for beginners. You don't even need to browse the 
> repository files, we have links in page footer that directly open the 
> right source file. But given that I regularly read people mentioning 
> that the workflow is the problem, I wonder How big is that? Do we have 
> any metrics (or reports) that this is what discourages people from 
> contributing. I'm used to it so I'm probably blind and not the right 
> person to evaluate but I'd like to hear what are the actual features 
> that are problematic.
> We've written a step-by-step contribution doc for beginners years ago 
> [1] and try to improve it over the years. Maybe it's not clear enough 
> or it's not just enough or nobody is aware of it (other than 
> Australian of course, Andrew) but without feedback, it's hard to know 
> what people want.
>
> I remember years ago, Tim on behalf of the PSC made a call for doc 
> contributions [2]. No git, no github, no rst, simply provide a .txt 
> (or whatever you are used to) file that addresses a doc issue. So 
> clearly, no degree required. We got, from memories, no more than two 
> reports though I only can find one [3].
> I don't know where the issue resides given all the options we all have 
> already tried.
>
>>     I suggest working out a budget for this, to check how feasible this
>>     solution can be, before taking further steps.
>
Yes, good idea, a budget item should go on the next steps list.
>
>>     Another radically different solution would be to embrace the chaotic
>>     approach, and leave the user browsing the thousands of web
>>     resources to
>>     get help, and keep official documentation to an absolute bare minimum
>>     that we can effectively managed by the core team. I'm not a fan
>>     of this
>>     solution, but it what is currently happening.
>
> Yeah! This is why I suggested months ago that we made a "User question 
> of the month" on where/how people learn QGIS features and whether they 
> know about and use our docs. It does not make sense to invest in 
> something nobody uses, right? Unfortunately, we did not make it. Maybe 
> should we.
>
> I'm glad to confirm there are a lot of people concerned by the docs 
> status and I wish we find tangible actions that revitalize QGIS docs 
> (if it's what the project and the community need). Thanks Cameron. But 
> I must also confess that I'm jealous of this thread and disappointed I 
> got no reply to my less-than-a-week wishlist message [4] that intended 
> to help QGIS Docs **actual writers**.

Harrissou, I feel for you. I've had plenty of knock backs in my 20+ 
years of open source project work. My advice is "Don't take it 
personally. Don't stop trying, but do consider trying different reach 
out techniques till you find one that works."

I'm a strong believing in connecting with people one-on-one. Listen to 
people at the next conference, or tutorial class you are at. People will 
often say something like "I'd love to help with XXX, but am not sure 
how". If you can give suggest a small task, that ideally will be very 
valuable, and then keep checking up on them in case they get stuck.

I'm not sure if you read this, but this is the research which backs this 
up (in much more detail)

http://cameronshorter.blogspot.com/2018/12/catching-elusive-episodic-volunteer.html


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20190829/81d76fa1/attachment.html>