<div dir="auto">Hi Cameron,<div dir="auto">Hi Grant,</div><div dir="auto"><br></div><div dir="auto">I think we have already swapped some messages on twitter some time ago.</div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto"><a href="https://github.com/qgis/QGIS-Documentation/issues">https://github.com/qgis/QGIS-Documentation/issues</a><br></div><div dir="auto"><br></div><div dir="auto">The easier way to start editing the documentation is using github web interface. The following the instructions can help:</div><div dir="auto"><br></div><div dir="auto"><a href="https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html#using-the-github-web-interface">https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html#using-the-github-web-interface</a><br></div><div dir="auto"><br></div><div dir="auto">Very important: don't be afraid to "break" something, there will be people helping you to make it well.</div><div dir="auto"><br></div><div dir="auto">English review is also very welcome.</div><div dir="auto"><br></div><div dir="auto">Thanks,</div><div dir="auto"><br></div><div dir="auto">Alexandre Neto</div><div dir="auto"><br></div><div dir="auto"><br></div><div dir="auto"><br></div><br><br><div class="gmail_quote" dir="auto"><div dir="ltr" class="gmail_attr">A domingo, 22/12/2019, 20:07, Cameron Shorter <<a href="mailto:cameron.shorter@gmail.com">cameron.shorter@gmail.com</a>> escreveu:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div text="#000000" bgcolor="#FFFFFF">
<p>Combining a couple of emails, and looping in
<a href="mailto:qgis-community-team@lists.osgeo.org" target="_blank" rel="noreferrer">qgis-community-team@lists.osgeo.org</a></p>
<p>Grant's email shared with his permission ...<br>
</p>
<div>On 21/12/19 10:51 am, Grant Boxer
wrote:<br>
</div>
<blockquote type="cite">
<p>Hi Cameron,</p>
<p>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.</p>
<p>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)?<br>
</p>
<p>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)?<br>
</p>
<p>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.</p>
<p>Cheers Grant</p>
</blockquote>
<p>Grant and I had a follow up call. A few highlights:</p>
<p>* 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.</p>
<p>* 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: <br>
</p>
<p><i>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.</i></p>
<p>Rest of the essay (and video) here: <a href="https://www.divio.com/blog/documentation/" target="_blank" rel="noreferrer">https://www.divio.com/blog/documentation/</a><br>
<i></i></p>
<p>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.</p>
<p>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.</p>
<p>Help ensure the "QGIS 101" tutorial is excellent. This would
involved:<br>
* Aligning the tutorial format with emerging best practices in
TheGoodDocsProject <a href="https://thegooddocsproject.dev/" target="_blank" rel="noreferrer">https://thegooddocsproject.dev/</a><br>
* Reviewing existing material and ensuring it is up to date with
latest software (probably the long-term-release version).<br>
* Attracting and coordinating reviews from the greater QGIS user
community.<br>
* Supporting the QGIS user documentation to update docs with git
and wiki formats. (You can lean on developers and
TheGoodDocsProject to help with that.</p>
<p>Re schedule:<br>
* I suggest start by assessing the size of the problem.<br>
* The reach out to communities with a proposed approach.<br>
* Ask questions and hopefully attract collaborators along the way.</p>
<p>Note:<br>
* 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.<br>
* I expect the QGIS docs team will help with technical and
structural questions you have.<br>
* I'm involved in TheGoodDocsProject and plan to help with
templates through that community.<br>
* 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.</p>
<p><br>
</p>
<blockquote type="cite">
<p><br>
</p>
<div>On 21/12/2019 1:41 am, Cameron
Shorter wrote:<br>
</div>
<blockquote type="cite">
<p>Hey Grant,</p>
<p>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.)<br>
</p>
<p>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])<br>
</p>
<p>I wonder whether you (and others) might be interested in
helping to solve this in 2020?</p>
<p>I think this is the sort of project us Australians are
uniquely placed to solve:</p>
<p>* We have this QGIS user group as a starting point.</p>
<p>* 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.<br>
</p>
<p>* 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.</p>
<p>So we should be good at helping solve QGIS docs' problems.
Would helping QGIS docs in 2020 be of interest?<br>
</p>
<p>[1] <a href="http://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html" target="_blank" rel="noreferrer">http://cameronshorter.blogspot.com/2019/12/why-qgis-docs-team-is-struggling.html</a></p>
<p>[2] <a href="https://thegooddocsproject.dev/" target="_blank" rel="noreferrer">https://thegooddocsproject.dev/</a>
(Best practice templates for documenting open source software)<br>
</p>
<div>On 19/12/19 2:38 pm, Grant Boxer
wrote:<br>
</div>
<blockquote type="cite">
<div dir="ltr">
<div>Hi Everyone,</div>
<div><br>
</div>
<div>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).</div>
<div><br>
</div>
<div>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.<br>
</div>
<div><br>
</div>
<div>Cheers Grant Boxer</div>
<div><br>
</div>
</div>
-- <br>
You received this message because you are subscribed to the
Google Groups "QGIS Australia User Group" group.<br>
To unsubscribe from this group and stop receiving emails from
it, send an email to <a href="mailto:australian-qgis-user-group+unsubscribe@googlegroups.com" target="_blank" rel="noreferrer">australian-qgis-user-group+unsubscribe@googlegroups.com</a>.<br>
To view this discussion on the web, visit <a href="https://groups.google.com/d/msgid/australian-qgis-user-group/da343dba-2dc0-4e99-838c-aa6880385434%40googlegroups.com?utm_medium=email&utm_source=footer" target="_blank" rel="noreferrer">https://groups.google.com/d/msgid/australian-qgis-user-group/da343dba-2dc0-4e99-838c-aa6880385434%40googlegroups.com</a>.<br>
</blockquote>
<pre cols="72"></pre>
</blockquote>
</blockquote>
<pre 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" rel="noreferrer">Qgis-community-team@lists.osgeo.org</a><br>
<a href="https://lists.osgeo.org/mailman/listinfo/qgis-community-team" rel="noreferrer noreferrer" target="_blank">https://lists.osgeo.org/mailman/listinfo/qgis-community-team</a></blockquote></div></div>