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

Thu May 30 22:25:02 PDT 2019

Hi Jared,

I am happy to open up access to that document and work on it with anyone
who is interested. That document should now be accessible to all with the
link.

Just for some context those notes were my cheat sheet as a newbie for
navigating through this existing QGIS documentation for a "Step by Step
Contribution" -
https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html

The intention I always hand in mind was to be able to amend the above guide
to make it clear for a new documenter and GitHub novice.

Excited to collaborate with others to improve it.

Thanks
Andrew

On Wed, May 29, 2019 at 9:57 PM Jared Morgan <jaredleonmorgan at gmail.com>
wrote:

>
>>
>> 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)?
>>>
>> _______________________________________________
> 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/20190531/42a921f7/attachment-0001.html>