[SeasonOfDocs] Hello

[Brian McRae]

Hi All,

I've been a member of the Aus-NZ-QGIS-group for a while, quietly receiving
emails. I took up Cameron's invitation for volunteers to support the GSOD
initiative yesterday. Since then, I've:

   - Read a few group emails (those that were sent since I joined)
   - Scanned the rest of the group messages to date
   <https://lists.osgeo.org/pipermail/seasonofdocs/> (mostly thread titles,
   just to get an idea of where the group has been / is up to)
   - Perused Andrew's doc on Getting started with QGIS documentation
   <https://docs.google.com/document/d/1eWpqmZHFiuoUhcCPcf9VTFrs2ol53A-Ha9in8sbiwlU/edit>
(thanks
   to Cameron for the link; this looks quite helpful and I'll spend some more
   time with it)
   - Read the OSGeo Wiki page Season of Docs Ideas 2019
   <https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019> (but not
   explored links, etc.)

This has given me some ideas about the project, along with some questions,
including a fair bit of uncertainty about what I might be wrong about
and/or might be missing. I figured a 'hello' email would be a good start. I
included links above as these might be useful to other people that join
down the road. (One idea might be a 'welcome' email.)

I haven't been able to get access to edit the Wiki yet, but my brief bio
might read something like:

*Environmental scientist/planner/bureaucrat; IT hack most of my life
(starting with TTY, paper tape and punchcards & 5.25" floppys); with a
passion for understanding and improving systems, including relationships.
This includes a few decades playing with various GIS packages, including
the two main commercial offerings, as well as QGIS. Communication has been
a key career theme, mostly about technical issues, for a range of
audiences, using different mediums. I'm keen to use this opportunity to
grow a bit - I haven't written documentation - and to express my deep
appreciation for QGIS, and its community, by contributing.*

Regarding the SOD project, I'm struck by a relative absence in the
discussion about 'audience' (a critical element for me in my writing
experience). It does arise, as does the question of the larger landscape of
resources (e.g. documentation, tutorials, etc.). As I've only
scanned/perused the discussion to date, this observation may be
unwarranted. In addition, as this project is still at the inception, I
might be looking for too much structure. However, my thought process is
along these lines:

   - The 'audience' (OSGEO users?) is huge/diverse, with varied needs
   - Any attempt to provide a single solution (e.g. writing documentation
   for both newbies and experts) is destined to be a compromise and not serve
   either end of the spectrum ideally
   - Fortunately, the FOSS/OSGEO/QGIS community contributes and creates
   lots of resources including some great blogs, forums such as StackExchange,
   etc.
   - As a self-described IT-hack, when I have a question I typically do a
   Google search and the source/sources I often find most useful are not the
   'official' QGIS documentation
   - Some sort of 'portal' site, or at least a wiki-type facility within
   the documentation that supports the listing of links to other/external
   information sources, possibly with an opportunity of community
   contributions (comments), might be a useful contribution, or a component of
   one or more ideas/projects

I wrote most of this yesterday, and then saw Jared's email, where he raised
a lot of the questions on my mind, such as:

   - Do we have a learning vision
   - What types of documentation do we want to create (including a list of
   categories from his current work: Tutorial, How-to, Discussion, Reference)
   - Complemented by Matteo's earlier email in the thread about 3 main
   resources (QGIS user manual - explaining buttons; QGIS Training Manual; and
   PyGIS cookbook)
   - Consulting QGIS Docs <https://www.qgis.org/en/docs/index.html> I'd
   suggest Matteo's list of three QGIS resources (for users) should actually
   be:
      - User Guide
      - Training Manual; and
      - A Gentle Introduction 'in' (to) QGIS
   - These resources for Users are complemented by:
      - Documentation Guidelines (for document writers); and
      - Three resources for developers (including PyGIS Cookbook and the
      documentation for C++ and PyGIS APIs)
   - What is the target persona (audience) - with a reply that I can't find
   indicating that the audience is to an extent unknown, but is also diverse
   (but I note the wiki ideas include some "WHY?" explanations that provide
   stats on common user complaints/suggestions - very important/useful IMHO)

Apologies for the lengthy post. My intent is mostly to add a hello,
including my observations as a new arrival to this process - what the
landscape looks like from my perspective. I warned in my bio that I am
oriented towards systems thinking, but I'm bolstered by the fact that
Jared, as an experienced technical writer but new to GIS, echoed some of my
concerns.

In summary, I think my key point would be:

   - I think it is important to have a clear context (overview), notably
   the relationships between:
      - Audience(s)
      - OSGEO/QGIS documents/resources; and
      - Other external documents/resources (including the FOSS4G GeoAcademy
      Curriculum <http://spatialquerylab.com/foss4g-academy-curriculum/>,
      and Ujaval Gandhi's tutorials
      <https://www.qgistutorials.com/en/index.html>, as well as other
      resources he lists
      <https://www.qgistutorials.com/en/docs/learning_resources.html>)

This understanding of the landscape (need a map :-) potentially increases
the chance of creating useful content, whether by providing clear direction
for the revision of an existing component or assisting with the
identification of gaps/opportunities, such as the 'portal' approach I
suggest above. One resource (FeldyNotebook
<https://feldynotebook.com/edges-of-the-feet-ay433/>) I've been involved in
contributing to, whilst completely unrelated in terms of subject matter and
audience, perhaps offers some useful concepts, such as:

   - A standard template (subject headings)
   - Cross-referencing
   - External links
   - Invitation for comments

Cheers, Brian

<http://linkedin.com/in/bpmcrae>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190530/f25ad3aa/attachment.html>