<html><head></head><body>Hi Cameron and all,<br><br>I did not actively follow the discussion nor fully understand how the GSOD program will be organized, what actually can a senior technical writer provide as expertise but I'm already glad to see the interest of the wider OSGeo community in improving and learning from QGIS doc. It's nice to read comments from others than the Core QGIS writers or issue reporters. I don't know whether what I will raise below can be handled by the program and did not take the time to structure my thoughts (sorry) but I'd like to share things we do or want to do, and hear from other projects how they do.<br><br>Cameron, I share the points you compiled below, and thanks to all of you for your contributions.<br>I'd simply have expected that the step by step chapter is now accessible to beginners. We made an in-depth review few months ago, with (I may be wrong) the help of a writer and a "beginner". But still if you don't have enough potential contributors to test the process and tell you where they struggle to step in, it's hard for advanced contributors to find the right level to lower the barrier. That doesn't mean that what we did is perfect; if there's a way to improve and someone can help, it's more than welcome. Nick, for reference, last year Alexandre Neto made a video for first contribution to docs [0]; we should have added to the guidelines but forgot. It may need some cleanup but could maybe help you in your plan.<br><br>We, at QGIS, but I guess it's the same for all our projects, are lacking writers. Even call for paid writers failed in the past. I don't know whether a senior writer can help us understand why and find how to fix it but, it could be nice...<br><br>I've been contributing to QGIS doc for years and one thing I miss is a cap, a direction. What are the priorities? So I just adress "what I want, when I can". Or when I catch some requests on the mailing lists. Might not be different for others, I think. Until recently, we had a contributor asking what she should first focus on and no clear answer arose so yes, if someone can help us to get a strategy of writing, I'd be glad. And also define schedules, plan when releases should be better done. We do it greatly IMHO with the application, it could be nice to have the same for docs release. Experience from other projects may help here.<br><br>One of the strengths of QGIS Docs is the tightness we are building with the devs. For example, most of the dialogs (should) have a help button that opens online the feature page in the corresponding language of the user manual if available. In the future, the docs would be available locally. <br>Also, Most of our 400 issue reports are automatically generated by commits in QGIS code so we directly have what we should write about in the doc repo. But this becomes a weakness when:<br>- there's not enough people to write (increasing number of issues), <br>- there's no cleanup for duplicate issues (because of backports) or unrelated issues (eg API matters) --- we try to fix these ones<br>- or the commit message is not clear enough for writers (who may not have the same technical knowledge as the developer). If we can get some clues on how to make devs write more detailed description in noob language, big +1<br><br>I think that triaging the issue tracker and setting priorities and deadlines may greatly help in telling where a senior writer can help (in writing, I mean). I'm not sure any of us (at least me, I do not) have the actual big picture of the issue reports and can categorize them. We already have the necessary tags but now we need to use them. So this would be my task 1.<br><br>As Richard or Matteo mentioned, we are also reviewing the global formatting/rendering of the docs. Whether we move to readthedocs. In the meantime, we think it could be nice to improve the rendering of the Processing algorithms docs [1], looking for something more compact and easy to read. An initial work is done [2] and if we can get more help to finish the prototype and apply it could be nice.<br><br>Another issue we can have is that most of us are not English native speakers. So a review of the docs from an English speaker is more than desired. But I'm not sure if for this, we necessarily need the person to be a senior writer.<br><br>The training materials (dataset and instructions) are also an important item. We are still working on updating to QGIS 3 and I'm happy if there's a demand (/an offer?) to structure and join efforts on this area. But to be honest, I'm more interested in translatable docs (because I'm not in an English working environment and "my" community wouldn't reuse it otherwise) than building an English only infrastructure. So it could be nice if we keep the translatability (?) in mind. Maybe, another topic.<br><br>Sorry for the lengthy message. I hope there are information that clarify what we do, that you can pick and improve our submission. But whatever the result for GSOD, I think there are a lot of ideas in this thread we should try to implement in the long run.<br><br>[0] <a href="https://github.com/qgis/QGIS/wiki/20th-Developer-Meeting-in-Madeira,-February-2018#making-your-first-pull-request-to-qgis-documentation">https://github.com/qgis/QGIS/wiki/20th-Developer-Meeting-in-Madeira,-February-2018#making-your-first-pull-request-to-qgis-documentation</a><br>[1] eg <a href="https://docs.qgis.org/3.4/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html">https://docs.qgis.org/3.4/en/docs/user_manual/processing_algs/qgis/vectorgeometry.html</a><br>[2] <a href="https://github.com/qgis/QGIS-Documentation/pull/2770">https://github.com/qgis/QGIS-Documentation/pull/2770</a><br><br>PS: Since people were asking, the best way to contact the QGIS Doc team is to use the dedicated list qgis-community-team@lists.osgeo.org as mentioned at <a href="https://www.qgis.org/en/site/getinvolved/mailinglists.html#qgis-community-team">https://www.qgis.org/en/site/getinvolved/mailinglists.html#qgis-community-team</a><br><br>Regards,<br>Harrissou Sant-anna<br><br><br><div class="gmail_quote">Le 22 avril 2019 15:03:35 GMT+02:00, Cameron Shorter <cameron.shorter@gmail.com> a écrit :<blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">
<div dir="ltr">I've updated the QGIS Season of Docs ideas, based on ideas on this list so far. Thanks for your ideas, especially thanks to Andrew for writing it out so clearly.<div><br></div><div><a href="https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS">https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS</a><br></div><div><p style="margin:0.5em 0px;line-height:inherit;color:rgb(37,37,37);font-family:sans-serif;font-size:14px">QGIS, a desktop GIS application, is one of the OSGeo Foundation’s flagship projects with a broad developer and documentation community. QGIS core documentation is comprehensive and there is a diverse ecosystem of organisations and people who have created QGIS workshops and training courses. However, it is challenging for documenters to keep up with QGIS’s rapid innovation, to sustainably keep the breadth of documentation current, consistent, and targetted.</p><p style="margin:0.5em 0px;line-height:inherit;color:rgb(37,37,37);font-family:sans-serif;font-size:14px">Season of Docs ideas for QGIS include the following:</p><ul style="margin:0.3em 0px 0px 1.6em;padding:0px;color:rgb(37,37,37);font-family:sans-serif;font-size:14px"><li style="margin-bottom:0.1em">Get assistance from writers to create a simple, and clear "quickstart". WHY? Because 11 of the 26 threads started in 2019 on the Australian user group are related to getting started, loading and exporting data. People indicate that they have referred to the documentation but are still lost.</li><li style="margin-bottom:0.1em">Review the structure of current documentation and provide clear separation of tasks. WHY? Because there is a "Getting started" section in the user manual and also a separate documentation section on "Getting started with GIS" - Which route does a new user take? And is the best place for Getting started material to be nested in other material? A writer could assist with by defining the best practice structure.</li><li style="margin-bottom:0.1em">Writers to review the language and readability of the QGIS "Step by Step contribution" (This is documentation for making documentation contributions). - <a rel="nofollow" class="external gmail-free" href="https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html" style="text-decoration-line:none;color:rgb(102,51,102);background-color:initial;padding-right:13px">https://docs.qgis.org/3.4/en/docs/documentation_guidelines/first_contribution.html</a> - WHY? This guide walks a user through making a contirbution to the QGIS documentation. I don't believe the method for maintaining documentation will change, so let's reduce the contributor’s barrier to entry by making this section so accurate and clear that anyone can pick it up.</li><li style="margin-bottom:0.1em">Triage and then manage QGIS documentation issue tracker. Audit the status of QGIS documentation. Publicly share status, strategy, and vision which will help volunteers know how to engage, and what impact they can provide.</li><li style="margin-bottom:0.1em">There are a number of geospatial training courses which cover a range of topics. Merging all these courses into a central source is not logical or desirable. However, there would be value in consolidating the geospatial and QGIS basics into a central base. This will be challenging, but valuable, and would require both excellent writing and coordination skills. Some of the content authors are already committed to sharing and supporting such an initiative. Others will likely come on board once momentum grows.</li></ul><p style="margin:0.5em 0px;line-height:inherit;color:rgb(37,37,37);font-family:sans-serif;font-size:14px">Resources:</p><ul style="margin:0.3em 0px 0px 1.6em;padding:0px;color:rgb(37,37,37);font-family:sans-serif;font-size:14px"><li style="margin-bottom:0.1em"><a rel="nofollow" class="external gmail-text" href="https://www.qgis.org/en/docs/index.html" style="text-decoration-line:none;color:rgb(102,51,102);background-color:initial;padding-right:13px">QGIS Documentation</a></li><li style="margin-bottom:0.1em"><a rel="nofollow" class="external gmail-text" href="https://github.com/qgis/QGIS-Documentation/issues" style="text-decoration-line:none;color:rgb(102,51,102);background-color:initial;padding-right:13px">QGIS Documentation Issues</a></li><li style="margin-bottom:0.1em"><a rel="nofollow" class="external gmail-text" href="http://spatialquerylab.com/foss4g-academy-curriculum/" style="text-decoration-line:none;color:rgb(102,51,102);background-color:initial;padding-right:13px">University-level lectures and labs, created by GeoAcademy</a> (based on the older QGIS 2.18)</li><li style="margin-bottom:0.1em"><a rel="nofollow" class="external gmail-text" href="https://www.gaiaresources.com.au/qgis-vids/" style="text-decoration-line:none;color:rgb(102,51,102);background-color:initial;padding-right:13px">Environmental QGIS training and videos</a> from Gaia Resources (based on the older QGIS 2.18)</li></ul></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, 21 Apr 2019 at 08:22, Cameron Shorter <<a href="mailto:cameron.shorter@gmail.com">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">
  
    
  
  <div bgcolor="#FFFFFF">
    <p>Hi folks, <br>
    </p>
    <p>I'm struggling to compile QGIS writing tasks for SeasonOfDocs
      which are as compelling as Jo and Maria have put together for
      GeoNetwork:</p>
    <p><a href="https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork" target="_blank">https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#GeoNetwork</a></p>
    <p> I'm hoping that those of you who have used QGIS docs can list
      strengths and then be fully transparent about its weaknesses. If
      we don't have much of a problem, something requiring senior
      technical writer expertise, then why would Google want to help us?
      There will be plenty of worthy projects for Google to select from.</p>
    <p>We have 3 days (till 23 April) to respond. Could you please help
      by brainstorming ideas in this email thread. I'll commit to
      compiling them into <a href="https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS" target="_blank">https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS</a>
      . (Although feel free to update it yourself.)<br>
    </p>
    <p>Ideas I'm considering based on the conversations so far:</p>
    <p>* There appears to be a high technical barrier to entry which
      makes it hard for new users to engage with improving QGIS docs. Is
      this so? What writing tasks could we put in place to address this?<br>
    </p>
    <p>* OSGeoLive has successfully attracted authors from ~ 50 projects
      to write Quickstarts and Project Overviews based on clear
      templates and writing guides. Would a template/writing guide be
      useful for QGIS? For what doc types? Workshops? Tutorials? (I'm
      suspecting these to be in the sweet spot for us, as they could be
      rolled out through OSGeoLive to other projects).<br>
    </p>
    <p>* "<i>Training materials are generally tailored to a customer,
        their technical use case, using sample maps from the customer's
        location in the world. This makes it difficult to develop
        consolidated material that works for everyone". </i>However<i>,
        "there's a really big need for standard training materials- and
        also if possible the kind of training materials that could be
        used for schools, to try to break the monopoly that certain
        proprietary companies have on that area."</i> How can we define
      this task more clearly?</p>
    <p>* The GeoNetwork team have provided an honest statement about the
      quality and completeness of their documentation. Does QGIS
      documentation have similar limitations? (My initial skim over docs
      suggest that the quality might be better, but I could be wrong.)</p>
    <p>* QGIS has had a major feature update from 2.18 to 3.4.x. I
      suspect we should talk about this? What documentation still needs
      to be updated or improved as a consequence?</p>
    <p>* With a rapidly innovating product like QGIS, with large
      documentation base, we could be running into challenges around
      maintenance and sustainability. Do you consider this a problem? If
      so, can you provide examples we can reference? Do you have
      suggestions on writing tasks to address this?<br>
    </p>
    <p>* Matteo mentions an issue tracker with over 400 writing tasks in
      it. How do we resource the management of these issues? We likely
      won't be allocated a <b>senior</b> writer to action such a list
      (Google's target for this initiative), but we might get a junior
      writer. This might not be supported until future Google writing
      initiatives, based on our identified need for such a role.</p>
    <p> * I'm aware that there are multiple QGIS training courses on the
      web, some which are free and open. Could you identify those that a
      tech writer should consider. You can list in the "Resources:" list
      in <a href="https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS" target="_blank">https://wiki.osgeo.org/wiki/Season_of_Docs_Ideas_2019#QGIS</a>
      . I notice that much of the training on the web is still based on
      version 2.18. Should we suggest effort be dedicated to updating
      them to 3.4?<br>
    </p>
    <p>----</p>
    <p>Please respond to this email with your ideas. I'll really
      appreciate the help.</p>
    <p>What follows are the emails and ideas I've based the above
      thoughts upon.</p>
    <p>Warm regards, Cameron</p>
    <p>----<br>
    </p>
    <ul style="list-style-type:disc;margin:0.3em 0px 0px 1.6em;padding:0px;color:rgb(37,37,37);font-family:sans-serif;font-size:14px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial">
      <br class="gmail-m_1455548889327654178Apple-interchange-newline">
    </ul>
    <p>Matteo's suggestions:</p>
    <ul style="list-style-type:disc;margin:0.3em 0px 0px 1.6em;padding:0px;color:rgb(37,37,37);font-family:sans-serif;font-size:14px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;text-align:start;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;background-color:rgb(255,255,255);text-decoration-style:initial;text-decoration-color:initial">
      <li style="margin-bottom:0.1em">Pyqgis cookbook code snipped are
        now automatically tested, meaning that every new contribution
        will be rock solid and code snippets can be taken "as they are"
        and pasted in QGIS</li>
      <li style="margin-bottom:0.1em">Change the doc style to the more
        readable Read-The-Docs vanilla theme (fully supported by
        sphinx). A live example here<span> </span><a rel="nofollow" class="gmail-m_1455548889327654178external gmail-m_1455548889327654178free" href="https://qgis.org/test/en/" style="text-decoration:none;color:rgb(102,51,102);background-color:initial;padding-right:13px" target="_blank">https://qgis.org/test/en/</a>.</li>
      <li style="margin-bottom:0.1em">Besides from contents, writing
        documentation isn't easy because of the complex framework
        (sphinx, git, github, etc). Improving the WYSIWYG github editor
        would be a great enhancement</li>
      <li style="margin-bottom:0.1em">Cleaning the issue tracker in
        github (> 400 issue now) in many different ways: verifying
        issues, closing duplicates, make order in the labels, etc</li>
    </ul>
    <div class="gmail-m_1455548889327654178moz-cite-prefix">On 12/4/19 2:46 pm, Andrew Jeffrey
      wrote:<br>
    </div>
    <blockquote type="cite">
      
      <div dir="ltr">Hi,
        <div><br>
        </div>
        <div>I agree with Jo's respone to Camerons question. </div>
        <div><br>
        </div>
        <div>Training materials are generally tailored to a type of
          customer and I this believe makes it difficult to develop
          consolidated material that works for everyone. The
          similarities I do see in training material though is the
          basics, the kind of basics that are taught to new users like
          those in the education space.</div>
        <div><br>
        </div>
        <div>As Jo mentioned there is potential here to break a monolopy
          in this space, and get exposure to new users early in their
          development. What makes this even better is a solid training
          material base owned by the community can be used by anyone
          creating training material, providing a consistent training
          base whether you learn in your own time online or go to
          trainer "A". Effectively consolidating the "QGIS beginner"
          training material.</div>
        <div><br>
        </div>
        <div>Regards</div>
        <div><br>
        </div>
        <div>Andrew</div>
      </div>
      <br>
      <div class="gmail_quote">
        <div dir="ltr" class="gmail_attr">On Thu, Apr 11, 2019 at 2:21
          AM Jo Cook <<a href="mailto:jo.k.cook@gmail.com" target="_blank">jo.k.cook@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="ltr">HI All,
            <div><br>
            </div>
            <div><snip></div>
            <div><br>
            </div>
            <div>Secondly- Cameron's question about QGIS courses- we
              also run QGIS training courses in the UK, and I think
              there's a fairly wide market, both geographically, and in
              the types of customer. We are focused on integration with
              cloud technologies, such as delivering QGIS via AWS
              AppStream, and less on teaching people to use all of the
              functionality, for example for higher-end processing and
              analysis. Having said that, I think there's a really big
              need for standard training materials- and also if possible
              the kind of training materials that could be used for
              schools, to try to break the monopoly that certain
              proprietary companies have on that area.</div>
            <div><br>
            </div>
            <div>Regards</div>
            <div><br>
            </div>
            <div>Jo</div>
          </div>
          <br>
          <div class="gmail_quote">
            <div dir="ltr" class="gmail_attr">On Wed, Apr 10, 2019 at
              2:27 PM Cameron Shorter <<a href="mailto:cameron.shorter@gmail.com" 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">
              <div bgcolor="#FFFFFF">
                <p>Thanks for the introduction Nick. One thing that
                  puzzles me is that there appears to be a lot of people
                  setting up QGIS training courses and I would have
                  thought it would be beneficial of these separate
                  initiatives were to become more consolidated.</p>
                <p>I'd expect that consolidating workshops would be a
                  very valuable task, as it would focus the community
                  together.</p>
                <p>It would also be a suitably challenging task to bring
                  multiple threads together, and something that would be
                  worthy of a senior technical writer's expertise.</p>
                <p>What are people's thoughts on the current state of
                  available QGIS training courses? Is there potential to
                  consolidate? Or is everyone tailoring to their unique
                  user base? <br>
                </p>
                <p>Warm regards, Cameron<br>
                </p>
                <p><br>
                </p>
                <div class="gmail-m_1455548889327654178gmail-m_-8879180848396350800gmail-m_-8174159744361345516moz-cite-prefix">On
                  10/4/19 10:13 pm, Nick Bearman wrote:<br>
                </div>
                <blockquote type="cite">
                  <div dir="ltr"><snip>
                    <div dir="ltr">
                      <div><br>
                      </div>
                      <div>I'm keen to learn how to contribute more
                        effectively, particularly to QGIS documentation,
                        and I am also looking to run a workshop on how
                        to contribute to OS documentation at upcoming
                        FOSS4G UK event in Edinburgh, UK in Sept.</div>
                      <div><br>
                      </div>
                      <div>I am familiar with Git/GitHub and Markdown.
                        The RST format of the QGIS Documentation site
                        sometimes eludes me! I look forward to working
                        with you all. </div>
                      <br>
                    </div>
                  </div>
                </blockquote>
              </div>
            </blockquote>
          </div>
        </blockquote>
      </div>
    </blockquote>
    <pre class="gmail-m_1455548889327654178moz-signature" cols="72">-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254</pre>
  </div>

</blockquote></div><br clear="all"><div><br></div>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><div><span style="font-size:12.8px">Cameron Shorter</span><br></div><div>Technology Demystifier</div><div>Open Technologies and Geospatial Consultant</div><div><br></div><div>M +61 (0) 419 142 254</div><div><br></div></div><div><br><br></div></div></div></div></div></div></div></div></div>
</blockquote></div><br>-- <br>Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.</body></html>