[SeasonOfDocs] How should we focus OSGeo training within SeasonOfDocs?

[matteo]

Hi Jared,

>     One thought would be implementing some type of Git Flow for Docs.
>     I've posted a question on Write the Docs to see if there is any
>     prior art on using Git Flow for docs contributions. From what I
>     understand about the project, all docs changes end up in GitHub, so
>     if this is an actual barrier for new folks, we'll need to fix that. 
> 
>     Git Flow might be a possible answer to this. It is most likely not
>     the only answer.

are you sure git flow is an answer to the workflow difficulties? I'm
afraid we are putting other entropy in the system that might be
difficult to manage (installing other software, conflicts, etc). From my
point of view the most difficult part for new comers is to handle plain
text (+images, rst syntax with links, substitution..) and of course git.

the complexity of the whole framework guarantees us a clean history and
I'm afraid we have to deal with this entrance barrier.

>     Do we have a learning vision defined for the project? Where would I
>     find this?

what do you mean exactly here? The type of contribution an user wants to
add?

>     I'm currently testing out the four core documentation types
>     (Tutorial, How-to, Discussion, Reference) at work for our internal
>     documentation spaces in Confluence. The structure is working well,
>     and the templates I've created allow a very consistent page
>     presentation and predictable structure. 
> 
>     I've discovered that you can organise these docs in the following ways:
> 
>      1. Use a tagging strategy to label each documentation type at the
>         audience level. Present the docs with an audience focus, either
>         in a narrative structure or in topic-based (stand-alone or
>         self-contained) format.
>      2. Use a tagging strategy to label at the content type level. Sort
>         the content under its docs type, so folks can:
>          1. find tutorials if they are new, 
>          2. how-to guides to solve specific problems, 
>          3. discussions to learn conceptual or foundational info, 
>          4. reference to learn technical info about a product.
> 
> 
>     The content types can be transferred to any content format. And the
>     real benefit is that it's a huge help for new folks when working out
>     "how do I write".
> 
>     The other benefit is that if you write these doc types in an atomic
>     way, they make remixing them into training modules much easier than
>     you might think. 

so if I'm not understanding wrong you might want to refactor the
Training Manual in a more atomic way?

>     To answer this question do we have a collective understanding of the
>     types of people that use the software?
> 
>     Even if we start with some broad assumptions that we could capture
>     in a central location (maybe the wiki) that we could then flesh out
>     together.
> 
>     I already know that there will be folks here with far more insight
>     into the types of people that typically use the software, so time to
>     do a brain dump if it already hasn't been done.

not really. People use the Training Manual "as they want". GIS (so QGIS
too) attracts a wide type of users and I think the current situation of
the Training Manual is self explanatory. From the beginning (how to load
a layer) to spatial statistics.

I think having this "index" allows to get from general topics to more
detailed once. I image a scenario of geologists that don't know how to
use QGIS: so the start from the beginning and when they are comfortable
they can go to the more detailed chapters.

>     If you adopt a Plain Language approach to writing, you can lower the
>     barrier of entry to users where English is not their first language.
>     This can be beneficial in widening the reach of the project,
>     particularly in the Training space.
> 
>     It also paves the way for i18n (internationalisation) and l10n
>     (localisation) in the future, as the project scales.
> 
>     If this is a new concept for folks here, check out the
>     excellent https://www.plainlanguage.gov/about/definitions/ to learn
>     more. It takes a bit of getting used to at first, but the effort
>     invested is worth it. You can also cheat by using grammar linters
>     (tools that evaluate your text looking for patterns). 
> 
>     Check out http://www.hemingwayapp.com/ as one example. I use
>     Grammarly, which while not strictly a Plain Language linter, does a
>     pretty good job of helping you create prose with consistent grammar
>     (it's currently parsing my text real-time as I type this).

this hemingwayapp is very useful. Actually we mostly are not native
English speakers and there are native English people, not so skilled,
that volunteers just to correct the text and typos.

>         ** I'd be interested to hear Jared's thoughts from the
>         perspective of a
>         senior technical writer.
> 
>         * From the various owners of QGIS training material on this
>         list: Why
>         are you writing and using material outside of the core QGIS
>         repository?
>         What are your barriers to entry in getting back into a central
>         location
>         and collaborating on material development and maintenance)?

yes. As said we suggest to use the default dataset, but nobody will stop
a contribution with default data

Cheers and thanks

Matteo