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

Thu May 30 05:00:30 PDT 2019

Jared Morgan
M: +61413005479
Google+ <https://plus.google.com/u/0/117309635670089895654/posts/p/pub> |
Twitter <http://twitter.com/!#/jaredmorgs> | Facebook
<http://facebook.com/jaredmorgs>

On Wed, 29 May 2019 at 22:56, matteo <matteo.ghetta at gmail.com> wrote:

> 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.
>

It's great that you are raising these concerns, Matteo.

I wanted to pose this question to reveal some of the feelings around the
processes that are currently in place.

You are correct in that to use git-flow you do need desktop software
installed like Sourcetree.

Here's an interesting question to pose. If you could suggest your ideal way
of getting folks to contribute, what would that look like?

>
> >     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?
>

Apologies for not being specific enough here. What I'm curious about is
whether we have any overarching learning goals that we would like users to
get out of existing training modules.

And, if the goals are different for new modules, what would those learning
goals be.

I will be open with you all here: I've not got much experience with
training material creation. It's something I'd like to learn more about and
I think I'm in the right project to get this knowledge.

>
> >     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?
>

That is my initial suggestion. But it only makes sense to do this if it
adds value to the existing content.

For example, if we make the content more atomic, will this help the project
remix the docs into user manuals?

The goal is to reduce the work in producing user guides *and* training
materials. Essentially it boils down to "write it once, use it twice".

>
> >     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
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190530/632f319e/attachment.html>