<div dir="ltr"><div dir="ltr">Hi Jared,<div><br></div><div>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.</div><div><br></div><div>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" - <a href="https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html">https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html</a></div><div><br></div><div>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.</div><div><br></div><div>Excited to collaborate with others to improve it.</div><div><br></div><div>Thanks<br>Andrew</div><div><br></div><div><br></div></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, May 29, 2019 at 9:57 PM Jared Morgan <<a href="mailto:jaredleonmorgan@gmail.com">jaredleonmorgan@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="auto"><div dir="auto"></div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, 27 May 2019 at 06:37, Cameron Shorter <<a href="mailto:cameron.shorter@gmail.com" rel="noreferrer noreferrer" target="_blank">cameron.shorter@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Thanks Matteo for the suggestions.<br>
<br>
I'm keen to lean on the experience of you and our community here to <br>
discuss your "How to contribute" page:<br>
<br>
<a href="https://docs.qgis.org/testing/en/docs/training_manual/appendix/contribute.html" rel="noreferrer noreferrer noreferrer" target="_blank">https://docs.qgis.org/testing/en/docs/training_manual/appendix/contribute.html</a><br>
<br>
* Andrew Jeffry has been a newbie QGIS documented and has helped other <br>
newbies getting started, and has collated his experience here: <br>
<a href="https://docs.google.com/document/d/1eWpqmZHFiuoUhcCPcf9VTFrs2ol53A-Ha9in8sbiwlU/edit?usp=sharing" rel="noreferrer noreferrer noreferrer" target="_blank">https://docs.google.com/document/d/1eWpqmZHFiuoUhcCPcf9VTFrs2ol53A-Ha9in8sbiwlU/edit?usp=sharing</a> <br>
. Matteo and Harrissou:How do you suggest we go forward with improving <br>
the getting started experience with Andrew's insights? Should we invite <br>
Andrew to update existing getting started page with his material?<br></blockquote><div><br></div><div>If Andrew is willing, it might pay to open up his document and use the in-line commenting feature to add comments collaboratively. <br><br></div><div>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.</div><div><br></div><div>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. </div><div><br></div><div>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. </div><div><br></div><div>Git Flow might be a possible answer to this. It is most likely not the only answer.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
* The "How to contribute" page explains the mechanics of how to <br>
contribute, but where I see additional value in the SeasonOfDocs <br>
initiative is in addressing some of the meta issues. Answering questions <br>
like:<br>
<br>
** What content do we want to accept in the QGIS manual? How do we <br>
decide what is in/out?<br>
<br>
** How should each page fit within the greater documentation and <br>
learning vision?<br></blockquote><div><br></div><div>Do we have a learning vision defined for the project? Where would I find this?<br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
** What types of documentation do we want to create?<br></blockquote><div><br>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. </div><div><br></div><div>I've discovered that you can organise these docs in the following ways:<br><ol><li>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.<br></li><li>Use a tagging strategy to label at the content type level. Sort the content under its docs type, so folks can:</li><ol><li>find tutorials if they are new, </li><li>how-to guides to solve specific problems, </li><li>discussions to learn conceptual or foundational info, </li><li>reference to learn technical info about a product.</li></ol></ol><br>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".</div><div><br></div><div>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. <br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
** What is the target persona we wish to write to for each doc type?<br></blockquote><div><br></div><div>To answer this question do we have a collective understanding of the types of people that use the software?</div><div><br></div><div>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.</div><div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
** What writing style/tone should be applied?<br></blockquote><div><br></div><div>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.</div><div><br></div><div>It also paves the way for i18n (internationalisation) and l10n (localisation) in the future, as the project scales.</div><div><br></div><div>If this is a new concept for folks here, check out the excellent <a href="https://www.plainlanguage.gov/about/definitions/" rel="noreferrer noreferrer" target="_blank">https://www.plainlanguage.gov/about/definitions/</a> 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). <br><br>Check out <a href="http://www.hemingwayapp.com/" rel="noreferrer noreferrer" target="_blank">http://www.hemingwayapp.com/</a> 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).</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
** I'd be interested to hear Jared's thoughts from the perspective of a <br>
senior technical writer.<br>
<br>
* From the various owners of QGIS training material on this list: Why <br>
are you writing and using material outside of the core QGIS repository? <br>
What are your barriers to entry in getting back into a central location <br>
and collaborating on material development and maintenance)?<br>
</blockquote></div></div>
</blockquote></div></div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank">SeasonOfDocs@lists.osgeo.org</a><br>
<a href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs" rel="noreferrer" target="_blank">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote></div>