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

[Jared Morgan]

>
>
> On Mon, 27 May 2019 at 06:37, Cameron Shorter <cameron.shorter at gmail.com>
> wrote:
>
>> Thanks Matteo for the suggestions.
>>
>> I'm keen to lean on the experience of you and our community here to
>> discuss your "How to contribute" page:
>>
>>
>> https://docs.qgis.org/testing/en/docs/training_manual/appendix/contribute.html
>>
>> * Andrew Jeffry has been a newbie QGIS documented and has helped other
>> newbies getting started, and has collated his experience here:
>>
>> https://docs.google.com/document/d/1eWpqmZHFiuoUhcCPcf9VTFrs2ol53A-Ha9in8sbiwlU/edit?usp=sharing
>> . Matteo and Harrissou:How do you suggest we go forward with improving
>> the getting started experience with Andrew's insights? Should we invite
>> Andrew to update existing getting started page with his material?
>>
>
> If Andrew is willing, it might pay to open up his document and use the
> in-line commenting feature to add comments collaboratively.
>
> I've got a few observations that apply in-line, that would be too hard to
> grok (understand) if I added them into this thread.
>
> The work Andrew has done here is excellent and will be a good foundation
> for enhancements to some process improvements that could reduce
> contribution barriers.
>
> 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.
>
>
>> * The "How to contribute" page explains the mechanics of how to
>> contribute, but where I see additional value in the SeasonOfDocs
>> initiative is in addressing some of the meta issues. Answering questions
>> like:
>>
>> ** What content do we want to accept in the QGIS manual? How do we
>> decide what is in/out?
>>
>> ** How should each page fit within the greater documentation and
>> learning vision?
>>
>
> Do we have a learning vision defined for the project? Where would I find
> this?
>
>
>>
>> ** What types of documentation do we want to create?
>>
>
> 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.
>
>
>>
>> ** What is the target persona we wish to write to for each doc type?
>>
>
> 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.
>
>
>>
>> ** What writing style/tone should be applied?
>>
>
> 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).
>
>
>>
>> ** 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)?
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190529/d43c9990/attachment-0001.html>