[Qgis-community-team] [Aus-NZ-QGIS-group] Should we tackle QGIS docs in 2020?

Sun Dec 22 12:07:40 PST 2019

Combining a couple of emails, and looping in 
qgis-community-team at lists.osgeo.org

Grant's email shared with his permission ...

On 21/12/19 10:51 am, Grant Boxer wrote:
>
> Hi Cameron,
>
> happy to get involved. I have some time, as I work part-time, but do 
> not have spare funds for monetary support of QGIS, so assisting in 
> documentation is a way I can contribute back to QGIS.
>
> As per the discussions on link [1], are official written detailed docs 
> the way to go? Most people Google for their information, so perhaps 
> there is a "web-way" to do it? We need comprehensive documentation but 
> perhaps there is another way. The current "Help" buttons link back to 
> the QGIS documentation but maybe they should point to a variation of 
> QGIS documentation, maybe the chapter or paragraph describing a 
> feature but with added usage examples, or to external links (this 
> might be nightmare to administer)?
>
> Also having "how-to-do" documentation is useful but there are so many 
> variations on a theme that trying to catch all this would be very 
> difficult. Googling is usually the best way to go here. Trying to 
> capture all this world-wide knowledge is a challenge. Maybe we just 
> need to encourage a variety of users to post on-line and allow Google 
> to find them (Stack Exchange, YouTube, etc)?
>
> Anyway, as mentioned in [1], we probably need to help people get 
> started with documentation by finding the "low hanging fruit" to get 
> started. I have not tried the process but it needs to be easy to use 
> as otherwise it will put people of very quickly. It needs to be 
> something that if someone has a spare 30 mins, they can quickly do an 
> update.
>
> Cheers Grant
>
Grant and I had a follow up call. A few highlights:

* Grant has an email list of a few hundred people who he has provided 
training to. He reckons some of them might be up to helping as well. 
That sounds great. It is amazing how much a core team of 3 or 4 core 
volunteers can achieve within an open source community, if they have a 
clear vision, strong motivation, and someone keeping the team focused. 
I've seen it happen.

* In answer to Grant's question about whether we should just let people 
"google the docs". Yes, there is a place for googling docs, but there is 
also a place where writing targeted and complete documentation for 
specific doc types is hugely valuable. A really good argument for this 
(often quoted in tech writing circles), is Daniele Procida's essay on 
tech writing:

/There is a secret that needs to be understood in order to write good 
software documentation: there isn’t one thing called documentation, 
there are four. They are: tutorials, how-to guides, explanation and 
technical reference. They represent four different purposes or 
functions, and require four different approaches to their creation. 
Understanding the implications of this will help improve most software 
documentation - often immensely./

Rest of the essay (and video) here: 
https://www.divio.com/blog/documentation/
//

So Grant, how could you be most impactful within the QGIS community? You 
are a geologist, QGIS user and trainer. You are also a native English 
speaker. These skills would be really valuable for the current QGIS doc 
team - many of whom are programmers, European, and have English as a 
second language.

I'd suggest focus on one of the doc types, and make it excellent. 
Tutorials would be a logical fit. Alternatively you could tackle Howos 
or Quickstarts. While I know you would do an excellent job creating a 
geologist specific tutorials, (and probably have material immediately at 
hand), I suggest start at the core.

Help ensure the "QGIS 101" tutorial is excellent. This would involved:
* Aligning the tutorial format with emerging best practices in 
TheGoodDocsProject https://thegooddocsproject.dev/
* Reviewing existing material and ensuring it is up to date with latest 
software (probably the long-term-release version).
* Attracting and coordinating reviews from the greater QGIS user community.
* Supporting the QGIS user documentation to update docs with git and 
wiki formats. (You can lean on developers and TheGoodDocsProject to help 
with that.

Re schedule:
* I suggest start by assessing the size of the problem.
* The reach out to communities with a proposed approach.
* Ask questions and hopefully attract collaborators along the way.

Note:
* I think we will likely be able to attract a tech-writer from Google 
Season of Docs in 2020, which I assume will run again in 2020.
* I expect the QGIS docs team will help with technical and structural 
questions you have.
* I'm involved in TheGoodDocsProject and plan to help with templates 
through that community.
* I suspect we'll be able to attract collaborators from within the OSGeo 
Oceania community, as mentioned earlier, along with your friends you've 
trained in QGIS that you mentioned.

>
> On 21/12/2019 1:41 am, Cameron Shorter wrote:
>>
>> Hey Grant,
>>
>> Great to see that you are helping people to learn QGIS. Would you 
>> consider helping get your material into the QGIS core docs? (Warning 
>> - it likely will involve some hard work.)
>>
>> Over the last year, as a spin off from Google Season of Docs, I've 
>> been reviewing the QGIS docs initiative. They are struggling - for a 
>> bunch of reasons, but partly because they've had problems attracting 
>> works such as yours back into the QGIS core. (Detailed analysis at [1])
>>
>> I wonder whether you (and others) might be interested in helping to 
>> solve this in 2020?
>>
>> I think this is the sort of project us Australians are uniquely 
>> placed to solve:
>>
>> * We have this QGIS user group as a starting point.
>>
>> * John Bryant, of FOSS4G-Oceania chair fame, noted recently that we 
>> appear to be net consumers of Open Source and not so good at giving 
>> back. However, there is significant OSGeo interest from our region, 
>> and people wanting to promote OSGeo, we just haven't figured out how.
>>
>> * I've recently been getting involved in tech writing communities and 
>> have discovered that Australia punches above its weight when it comes 
>> to producing docs. Attendance at Australia's WriteTheDocs conference 
>> is big compared to other countries, Australians are prominent in 
>> WriteTheDocs forums and podcasts, an Australian started Google's 
>> Season of Docs program this year, and the emerging GoodDocsProject 
>> has more active Australians than any other nation. I'm guessing this 
>> is because: Australians are native English speakers, and our "can-do" 
>> lateral thinking approach fits well with Technical Writing.
>>
>> So we should be good at helping solve QGIS docs' problems. Would 
>> helping QGIS docs in 2020 be of interest?
>>
>> [1] 
>> http://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html
>>
>> [2] https://thegooddocsproject.dev/ (Best practice templates for 
>> documenting open source software)
>>
>> On 19/12/19 2:38 pm, Grant Boxer wrote:
>>> Hi Everyone,
>>>
>>> just a heads up that I have been running QGIS for Geoscientists 
>>> workshops for the Australian Institute of Geoscientists (AIG) for 
>>> the past few years, mainly in Perth but also in Brisbane, Hobart, 
>>> Sydney and Townsville. As part of this I have put together a geos 
>>> user manual to help geos find stuff that they need to do in QGIS - 
>>> much of which is not readily found by a Google search. If anyone is 
>>> interested in a copy , just shoot me an email to 
>>> "boxergatiinetdotnetdotau" and I will send you the link (feel free 
>>> to share).
>>>
>>> I am also pushing to get an advanced drill hole plugin written for 
>>> QGIS and if you would like to be in the loop, or be prepared to 
>>> assist in funding, please let me know. Roland Hill has done a great 
>>> job with his Geoscience plugin, but I feel we can have something 
>>> more 3D with integration with Postgresql. Any comments or 
>>> suggestions appreciated.
>>>
>>> Cheers Grant Boxer
>>>
>>> -- 
>>> You received this message because you are subscribed to the Google 
>>> Groups "QGIS Australia User Group" group.
>>> To unsubscribe from this group and stop receiving emails from it, 
>>> send an email to 
>>> australian-qgis-user-group+unsubscribe at googlegroups.com 
>>> <mailto:australian-qgis-user-group+unsubscribe at googlegroups.com>.
>>> To view this discussion on the web, visit 
>>> https://groups.google.com/d/msgid/australian-qgis-user-group/da343dba-2dc0-4e99-838c-aa6880385434%40googlegroups.com 
>>> <https://groups.google.com/d/msgid/australian-qgis-user-group/da343dba-2dc0-4e99-838c-aa6880385434%40googlegroups.com?utm_medium=email&utm_source=footer>.

-- 
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/20191223/023d718a/attachment.html>