[SeasonOfDocs] Hello

Thu May 30 04:44:08 PDT 2019

Welcome Brian.

I think you are suggesting excellent approaches to improving QGIS docs, 
which aligns with Jared's recommendations and suggestions from some of 
the other volunteers here. My  variant on the same theme is at [1].

Matteo, Harrissou, With the momentum we are building, I think we have 
potential to grow QGIS documentation into new areas and expand the QGIS 
documentation roadmap. Would you be interested in setting up a meeting 
to discuss this? (Probably select a timeslot of evening in Australia, 
lunchtime in Europe).

Brian, Your OSGeo wiki should now be approved, so please do add your 
name to the list of contributors.

[1] 
http://cameronshorter.blogspot.com/2019/04/amplifying-googles-season-of-docs.html

On 30/5/19 12:36 pm, Brian McRae wrote:
> 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:
>       o User Guide
>       o Training Manual; and
>       o A Gentle Introduction 'in' (to) QGIS
>   * These resources for Users are complemented by:
>       o Documentation Guidelines (for document writers); and
>       o 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:
>       o Audience(s)
>       o OSGEO/QGIS documents/resources; and
>       o 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>
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs

-- 
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/seasonofdocs/attachments/20190530/f5183128/attachment-0001.html>