<div dir="ltr"><a class="gmail_plusreply" id="plusReplyChip-2" href="mailto:emckean@google.com" tabindex="-1">+Erin McKean</a> <br><div>Adding Erin McKean, who is doing a lot of work around documentation guidelines and best practices for open source projects at every stage of the project lifecycle.</div><div><br></div><div>Sorry for brevity - have been in meetings continually</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Wed, Jun 26, 2019 at 3:26 PM 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>My brain dump additions to Felicity's skeleton embedded below.</p>
    <p>Felicity, you started a google doc earlier with some of your
      ideas. Do you think we should retask it to becoming the first
      draft of our vision doc? <br>
    </p>
    <div class="gmail-m_-123214357487461424moz-cite-prefix">On 26/6/19 10:57 am, Felicity Brand
      wrote:<br>
    </div>
    <blockquote type="cite">
      
      <div dir="ltr">
        <div dir="ltr">In the interest of starting discussions, here
          goes:
          <div>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt">I
              think articulating the goal is really important, as is
              defining our audience.
              This is going to drive everything.</p>
          </div>
        </div>
      </div>
    </blockquote>
    <p>We want to create a "best practices" guide and associated suite
      of templates for creating technical documentation for Open Source
      Software projects (as our primary use case). It will be almost
      directly applicable to all software projects and we should aim to
      cater for all software projects. It will be reasonably applicable
      to broader technical writing. While we should remain focused on
      our core audience, we should consider writing our documents such
      that they can be easily customised and extended into other
      domains. <br>
    </p>
    <p>Borrowing from Open Government design principles, we should "Do
      the hard work to make things Simple".</p>
    <p><a class="gmail-m_-123214357487461424moz-txt-link-freetext" href="https://www.gov.uk/guidance/government-design-principles#do-the-hard-work-to-make-it-simple" target="_blank">https://www.gov.uk/guidance/government-design-principles#do-the-hard-work-to-make-it-simple</a></p>
    <p>Rather than each organisations attempting to create their own
      writing guides, lets attract the cross section of communication
      expertise into one central community. Within our community of
      communicators, we will debate and decide upon best practices for a
      range of documentation types.</p>
    <p>We should capture a body of knowledge, referencing the best
      research and guides we can find. We should tailor components this
      knowledge to specific user groups. We could describe this as user
      stories. E.g.:<br>
    </p>
    <p>* As a software developer who needs to document my project, I
      need a template, clear writing instructions, and an example which
      I can easily adapt of follow.</p>
    <p>* As a documentarian reviewing a developer's docs, I want guides
      and and checklists to review against.</p>
    <p>I our next doc down from the vision should introduce the concept
      of a star rating for docs. Huge value can be gifted to projects by
      helping them get from the 1 star of "sort of covered docs" to the
      2 stars of having a techie align docs with templates. This now
      frees up tech writers to focus on the more challenging tasks of
      polishing and tailoring existing content.<br>
    </p>
    <p>...<br>
    </p>
    <blockquote type="cite">
      <div dir="ltr">
        <div dir="ltr">
          <div>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"> </p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt">I've
              briefly reviewed the excellent resources that already
              exist that people are
              pointing us to and my first reaction is that:</p>
          </div>
        </div>
      </div>
    </blockquote>
    I'm really interested to hear feedback on what is good or bad about
    the source material we have identified. Maybe create a list of our
    sources, and then comment on elements which we would want to bring
    into our master guide.<br>
    <blockquote type="cite">
      <div dir="ltr">
        <div dir="ltr">
          <div>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"> </p>
            <ul style="margin-left:0.375in;direction:ltr;unicode-bidi:embed;margin-top:0in;margin-bottom:0in" type="disc">
              <li style="margin-top:0px;margin-bottom:0px;vertical-align:middle"><span style="font-family:Calibri;font-size:11pt">We should
                  start with the assumption that good docs are good. We
                  don't need to bend over backwards articulating why.</span></li>
              <li style="margin-top:0px;margin-bottom:0px;vertical-align:middle"><span style="font-family:Calibri;font-size:11pt">We don't
                  need to train people *how* to write good docs.</span></li>
              <li style="margin-top:0px;margin-bottom:0px;vertical-align:middle"><span style="font-family:Calibri;font-size:11pt">We just
                  provide really excellent templates and guidance on how
                  to apply them.</span></li>
            </ul>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt">That
              is going to be the most useful and the TL;DR option for
              folks who have a messy
              open source project and want to bring it up to scratch.
              They're already
              motivated to improve their docs.</p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"><br>
            </p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt">We could point
              people to other resources if they want to dive deeper into
              the whys and hows.</p>
          </div>
        </div>
      </div>
    </blockquote>
    <p>Yes, and we might want to absorb and collate the other resources
      into our own dedicated sections.</p>
    <p>We want to avoid saying "Want to learn more? Go read these 10
      books, research papers, and blogs on the subject, and wade through
      tonnes of crap in order to find the gems. There will be a lot of
      value if we can increase the signal-to-noise ratio for all our
      stakeholders. (This is a slow burn activity).<br>
    </p>
    <blockquote type="cite">
      <div dir="ltr">
        <div dir="ltr">
          <div>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"> </p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt">Things
              like clarity, consistency, etc (the 5 C's) is something
              that most good tech
              writers know, so why do we need to articulate this again?</p>
          </div>
        </div>
      </div>
    </blockquote>
    <p>I just googled the 5 C's. Apparently there are 7.</p>
    <p>Our first target audience are techies who are writing docs
      (software developers and software users). Many will be like me and
      won't know the 5 C's, and won't need to know them if our templates
      are good enough.<br>
    </p>
    <blockquote type="cite">
      <div dir="ltr">
        <div dir="ltr">
          <div>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"> Are we
              teaching
              folk to write? Give a man a fish and you feed him for a
              day but teach a man
              to fish and you feed him for a lifetime. Are we teaching
              people to fish? I
              wouldn't have thought so... I think we're just giving
              people fish templates.
              OR, to strangle the metaphor further, giving people a
              baited<span style="font-size:11pt"> </span><span style="font-size:11pt">line in a barrel full of fish. So
                they are far
                more likely to succeed without having to learn to fish
                in the first place. <br>
              </span></p>
          </div>
        </div>
      </div>
    </blockquote>
    Yes, maybe it is a case of "bring your barrel of fish, we provide a
    stick of dynamite, you light the fuse."<br>
    <blockquote type="cite">
      <div dir="ltr">
        <div dir="ltr">
          <div>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"><span style="font-size:11pt"><br>
              </span></p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"><span style="font-size:11pt">So that's my first reaction.
                Happy to discuss further and I can't wait to see what
                everyone else thinks!</span></p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"><span style="font-size:11pt"><br>
              </span></p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"><span style="font-size:11pt">Cheers</span></p>
            <p style="margin:0in 0in 0in 0.375in;font-family:Calibri;font-size:11pt"><span style="font-size:11pt">Felicity</span></p>
          </div>
        </div>
        <br>
        <div class="gmail_quote">
          <div dir="ltr" class="gmail_attr">On Tue, Jun 25, 2019 at
            10:22 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>I'm feeling pretty special to be amongst a bunch smart
                tech writers who are keen create a "writing templates"
                project (and a quite a bit more).</p>
              <p>Here is what I suggest we do next:</p>
              <p>1. Over the next few weeks, lets start discussions on
                this <a class="gmail-m_-123214357487461424gmail-m_3584686751867454442moz-txt-link-abbreviated" href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank">SeasonOfDocs@lists.osgeo.org</a>
                email list.</p>
              <p>2. Between us, lets articulate our vision. I suggest we
                bounce ideas around on this list, and start collecting
                them into a Google doc that we collectively edit. I've
                been getting inspired by each of you on what this vision
                might be. We should think big, but make sure our first
                goals are very achievable.<br>
              </p>
              <p>3. Are there any existing projects which we should join
                instead of starting our own? <br>
              </p>
              <p>* Riona pointed to this project: <a href="https://github.com/kylelobo/The-Documentation-Compendium" target="_blank">https://github.com/kylelobo/The-Documentation-Compendium<br>
                </a></p>
              <p>* Stephanie pointed to: <a class="gmail-m_-123214357487461424gmail-m_3584686751867454442moz-txt-link-freetext" href="https://github.com/San-Francisco-Write-The-Docs/lone-writers-guide" target="_blank">https://github.com/San-Francisco-Write-The-Docs/lone-writers-guide</a> </p>
              <p>Does anyone know the people behind these projects? We
                should reach out to them. I'll be interested to hear
                thoughts on these projects.</p>
              <p>Lets discuss on email over the upcoming week. Next
                week, lets aim to decide if we are to join an existing
                project or start our own.<br>
              </p>
              <p>4. I suggest we set up a meeting next week with those
                of us who can make it. Maybe:</p>
              <table class="gmail-m_-123214357487461424gmail-m_3584686751867454442xpad gmail-m_-123214357487461424gmail-m_3584686751867454442border2" style="box-sizing:border-box;border-collapse:collapse;border-spacing:0px;background:rgb(255,255,255);text-align:left;border:1px solid rgb(221,221,221);color:rgb(69,69,69);font-family:Helvetica,Arial,sans-serif;font-size:14px;font-style:normal;font-variant-ligatures:normal;font-variant-caps:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration-style:initial;text-decoration-color:initial">
                <thead style="box-sizing:border-box;text-align:left"><tr class="gmail-m_-123214357487461424gmail-m_3584686751867454442head" style="box-sizing:border-box">
                    <th style="box-sizing:border-box;padding:5px 9px;text-align:left">Location</th>
                    <th class="gmail-m_-123214357487461424gmail-m_3584686751867454442sep" style="box-sizing:border-box;padding:5px 9px;text-align:left;border-left:1px solid rgb(204,204,204)">Local Time</th>
                    <th class="gmail-m_-123214357487461424gmail-m_3584686751867454442sep" style="box-sizing:border-box;padding:5px 9px;text-align:left;border-left:1px solid rgb(204,204,204)">Time Zone</th>
                    <th class="gmail-m_-123214357487461424gmail-m_3584686751867454442sep" style="box-sizing:border-box;padding:5px 9px;text-align:left;border-left:1px solid rgb(204,204,204)">UTC Offset</th>
                  </tr>
                </thead><tbody style="box-sizing:border-box">
                  <tr class="gmail-m_-123214357487461424gmail-m_3584686751867454442c0" style="box-sizing:border-box;background:rgb(255,255,255)">
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/worldclock/australia/sydney" title="Current local time in Sydney" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">Sydney</a><span> </span><span class="gmail-m_-123214357487461424gmail-m_3584686751867454442small" style="box-sizing:border-box;font-size:12.6px">(Australia
                        - New South Wales)</span></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">Tuesday,
                      2 July 2019 at 8:00:00 am</td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/time/zones/aest" title="Australian
                        Eastern Standard Time" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">AEST</a></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">UTC+10
                      hours</td>
                  </tr>
                  <tr class="gmail-m_-123214357487461424gmail-m_3584686751867454442c1" style="box-sizing:border-box;background:rgb(243,243,243);border-top:1px solid rgb(221,221,221);border-bottom:1px solid rgb(221,221,221)">
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/worldclock/usa/austin" title="Current
                        local time in Austin" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">Austin</a><span> </span><span class="gmail-m_-123214357487461424gmail-m_3584686751867454442small" style="box-sizing:border-box;font-size:12.6px">(USA
                        - Texas)</span></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">Monday,
                      1 July 2019 at 5:00:00 pm</td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/time/zones/cdt" title="Central
                        Daylight Time" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">CDT</a></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">UTC-5
                      hours</td>
                  </tr>
                  <tr class="gmail-m_-123214357487461424gmail-m_3584686751867454442c0" style="box-sizing:border-box;background:rgb(255,255,255)">
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/worldclock/usa/new-york" title="Current local time in New York" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">New York</a><span> </span><span class="gmail-m_-123214357487461424gmail-m_3584686751867454442small" style="box-sizing:border-box;font-size:12.6px">(USA
                        - New York)</span></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">Monday,
                      1 July 2019 at 6:00:00 pm</td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/time/zones/edt" title="Eastern
                        Daylight Time" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">EDT</a></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">UTC-4
                      hours</td>
                  </tr>
                  <tr class="gmail-m_-123214357487461424gmail-m_3584686751867454442c1" style="box-sizing:border-box;background:rgb(243,243,243);border-top:1px solid rgb(221,221,221);border-bottom:1px solid rgb(221,221,221)">
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/worldclock/uk/london" title="Current
                        local time in London" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">London</a><span> </span><span class="gmail-m_-123214357487461424gmail-m_3584686751867454442small" style="box-sizing:border-box;font-size:12.6px">(United
                        Kingdom - England)</span></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">Monday,
                      1 July 2019 at 11:00:00 pm</td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/time/zones/bst" title="British Summer
                        Time" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">BST</a></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">UTC+1
                      hour</td>
                  </tr>
                  <tr class="gmail-m_-123214357487461424gmail-m_3584686751867454442c0" style="box-sizing:border-box;background:rgb(255,255,255)">
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/worldclock/france/paris" title="Current local time in Paris" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">Paris</a><span> </span><span class="gmail-m_-123214357487461424gmail-m_3584686751867454442small" style="box-sizing:border-box;font-size:12.6px">(France
                        - Île-de-France)</span></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">Tuesday,
                      2 July 2019 at 12:00:00 midnight</td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none"><a href="https://www.timeanddate.com/time/zones/cest" title="Central
                        European Summer Time" style="box-sizing:border-box;background:transparent;color:rgb(85,107,181);text-decoration:none" target="_blank">CEST</a></td>
                    <td style="box-sizing:border-box;padding:0.4em;vertical-align:top;border:none">UTC+2
                      hours</td>
                  </tr>
                </tbody>
              </table>
              <p>(I can do earlier or later.)<br>
              </p>
              <p>5. A few of you were wanting to get clarifications from
                your organisations about open sourcing material. I
                suggest letting us know how that progresses. This might
                help <a href="http://cameronshorter.blogspot.com/2018/10/the-open-business-business-case.html" target="_blank">http://cameronshorter.blogspot.com/2018/10/the-open-business-business-case.html</a></p>
              <p>6. If we decide to start our own project, we will need
                to set up web pages, project structure and so on. If we
                join an existing project, we will likely need to help
                them do some of these things. We can start in a week or
                two.</p>
              <p>Okay, over to you. Please don't be shy - share your
                ideas and suggestions, and lets get this vision nailed
                down.<br>
              </p>
              <div class="gmail-m_-123214357487461424gmail-m_3584686751867454442moz-cite-prefix">On
                25/6/19 9:09 am, Riona Macnamara wrote:<br>
              </div>
              <blockquote type="cite">
                <div dir="ltr">Have you seen this? </div>
                <br>
              </blockquote>
              <pre class="gmail-m_-123214357487461424gmail-m_3584686751867454442moz-signature" cols="72">Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254</pre>
            </div>
          </blockquote>
        </div>
      </div>
    </blockquote>
    <pre class="gmail-m_-123214357487461424moz-signature" cols="72">-- 
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant

M +61 (0) 419 142 254</pre>
  </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>