Geological and Geoscience Applications of QGIS
Grant Boxer
Cameron Shorter
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)
--
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-use...@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.
-- Cameron Shorter Technology Demystifier Open Technologies and Geospatial Consultant M +61 (0) 419 142 254
Cameron Shorter
Combining a couple of emails, and looping in qgis-comm...@lists.osgeo.org
Grant's email shared with his permission ...
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.
Grant Boxer
Hi Alexandre,
OK thanks for that. Let me have a look on GitHub.
Cheers Grant
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.
The easier way to start editing the documentation is using github web interface. The following the instructions can help:
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
_______________________________________________
Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
Qgis-comm...@lists.osgeo.org
https://lists.osgeo.org/mailman/listinfo/qgis-community-team
