<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" 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="moz-cite-prefix">On 26/6/19 10:57 am, Felicity Brand
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CAEz4wU1TGuTz99njCqmjV5B8iK6=xH=gxYtq77waGCQ-iX+p3g@mail.gmail.com">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<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="moz-txt-link-freetext" href="https://www.gov.uk/guidance/government-design-principles#do-the-hard-work-to-make-it-simple">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"
cite="mid:CAEz4wU1TGuTz99njCqmjV5B8iK6=xH=gxYtq77waGCQ-iX+p3g@mail.gmail.com">
<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"
cite="mid:CAEz4wU1TGuTz99njCqmjV5B8iK6=xH=gxYtq77waGCQ-iX+p3g@mail.gmail.com">
<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"
cite="mid:CAEz4wU1TGuTz99njCqmjV5B8iK6=xH=gxYtq77waGCQ-iX+p3g@mail.gmail.com">
<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"
cite="mid:CAEz4wU1TGuTz99njCqmjV5B8iK6=xH=gxYtq77waGCQ-iX+p3g@mail.gmail.com">
<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"
cite="mid:CAEz4wU1TGuTz99njCqmjV5B8iK6=xH=gxYtq77waGCQ-iX+p3g@mail.gmail.com">
<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"
moz-do-not-send="true">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_3584686751867454442moz-txt-link-abbreviated"
href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank" moz-do-not-send="true">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" moz-do-not-send="true">https://github.com/kylelobo/The-Documentation-Compendium<br>
</a></p>
<p>* Stephanie pointed to: <a
class="gmail-m_3584686751867454442moz-txt-link-freetext"
href="https://github.com/San-Francisco-Write-The-Docs/lone-writers-guide"
target="_blank" moz-do-not-send="true">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_3584686751867454442xpad
gmail-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_3584686751867454442head"
style="box-sizing:border-box">
<th style="box-sizing:border-box;padding:5px
9px;text-align:left">Location</th>
<th class="gmail-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_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_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_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" moz-do-not-send="true">Sydney</a><span> </span><span
class="gmail-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" moz-do-not-send="true">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_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" moz-do-not-send="true">Austin</a><span> </span><span
class="gmail-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" moz-do-not-send="true">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_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" moz-do-not-send="true">New York</a><span> </span><span
class="gmail-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" moz-do-not-send="true">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_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" moz-do-not-send="true">London</a><span> </span><span
class="gmail-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" moz-do-not-send="true">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_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" moz-do-not-send="true">Paris</a><span> </span><span
class="gmail-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" moz-do-not-send="true">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" moz-do-not-send="true">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_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_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="moz-signature" cols="72">--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant
M +61 (0) 419 142 254</pre>
</body>
</html>