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

Sun Dec 22 15:32:03 PST 2019

Hi Cameron,
Hi Grant,

I think we have already swapped some messages on twitter some time ago.

The best way to help the QGIS Documentation team is to help us with our
main focus at the moment, the User's manual. From a recent meeting, it was
clear that the Training manual is not a priority (maybe because there are
lots of sources for tutorials and training in the www). Our secondary
target is the PyQGIS Cookbook, which fits more python programmers.

Our goal is to have all new features (<=3.10) documented in the user's
manual until the release of 3.10 as LTR, which will happen in February 2020.

All the new features to document are listed as github issues. Our goal now
is to tackle those that are labled as 3.10 or below.

https://github.com/qgis/QGIS-Documentation/issues

The easier way to start editing the documentation is using github web
interface. The following the instructions can help:

https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html#using-the-github-web-interface

Very important: don't be afraid to "break" something, there will be people
helping you to make it well.

English review is also very welcome.

Thanks,

Alexandre Neto

A domingo, 22/12/2019, 20:07, Cameron Shorter <cameron.shorter at gmail.com>
escreveu:

> 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.
> 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
>
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such
> as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/qgis-community-team
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-community-team/attachments/20191222/b4017861/attachment-0001.html>