<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
</head>
<body text="#000000" bgcolor="#FFFFFF">
<p>Love your ideas Clarence.</p>
<p>I particularly like your concept of a "Minimal Viable Docset".<br>
</p>
<p>Yes, I'd encourage you to start sketching out ideas for
templates, and starting to define personas of our target
audiences. <br>
</p>
<p>Probably start by adding ideas into Jo's Project Structure doc:</p>
<p><a
href="https://docs.google.com/document/d/1u656sQLSH5JspMvYqjuZuyCVTVwgIqisnyA6NO5AUgQ/edit">https://docs.google.com/document/d/1u656sQLSH5JspMvYqjuZuyCVTVwgIqisnyA6NO5AUgQ/edit</a></p>
<p><br>
</p>
<div class="moz-cite-prefix">On 16/7/19 7:05 am, Jennifer Rondeau
wrote:<br>
</div>
<blockquote type="cite"
cite="mid:CADTkFMevL29ttfKS-5iVVrNK_ojQ4VTygh3=tFNL2R1rb4RLbA@mail.gmail.com">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<div dir="ltr">+1000 to everything Clarence says here :D<br>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Mon, Jul 15, 2019 at 3:59
PM Clarence Cromwell <<a
href="mailto:clarencewcromwell@gmail.com"
moz-do-not-send="true">clarencewcromwell@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">On the topic of this survey, I don't understand
whether we're talking about markup that contributors to this
project would use, or the presumed language of the end-users
for the templates. (Do we need to think about markup
language of end-users?)
<div><br>
</div>
<div>Have we been considering something like a buildable
site? That seems exponentially more complicated than a
literal template.<br>
<div><br>
</div>
<div>Along that line of inquiry: What sort of deliverables
will this project create? </div>
<div><br>
</div>
<div>I have been thinking that end users would get the
most help from a template that looks like a document
outline, and that loosely describes what ought to be
included. That would be platform- and language-agnostic,
and would focus on the main benefit of this project
without getting bogged down in a lot of technical
questions.</div>
<div><br>
</div>
<div>For example: </div>
<div> </div>
<div>
<div><img src="cid:part3.A25A40AE.A66E3ECB@gmail.com"
alt="Screen Shot 2019-07-15 at 11.54.11 AM.png"
class="" width="472" height="129"><br>
</div>
</div>
<div>[. . .]</div>
<div><br>
</div>
<div>(This example applies to an API, although I know the
templates don't have to be that specific. It's also in
markdown, but I don't see any reason why an HTML
presentation of the outline wouldn't work.) </div>
<div><br>
</div>
<div>In addition to a plain outline, I would also advocate
for offering a model of a Minimum Viable Docset. I've
been talking to people about what is included in the MVD
when you roll out a new product. I've noticed that
mature products are frequently lacking key documentation
features that should have been included in the
beginning, and it seems that having a checklist of what
should be there, would make quite a difference.</div>
<div><br>
</div>
<div>(I'm sure the MVD would be slightly different for an
API, a cloud-based product, and a customer-hosted
product.)</div>
<div><br>
</div>
<div>I should add that many developers I've talked to at
Write the Docs are looking for this kind of direction.
They want to know what sort of document to create and
what goes in it, because they need just enough structure
to send them in the right direction. So an MVD model and
a set of document outlines would answer most of their
questions.</div>
<div><br>
</div>
<div>I hope it's not too soon, to dig into the nitty
gritty details of documentation templates. </div>
<div><br>
</div>
<div>Clarence</div>
<div><br>
</div>
<div><br>
</div>
</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Mon, Jul 15, 2019 at
8:12 AM Stephanie Blotner <<a
href="mailto:sblotner59@gmail.com" target="_blank"
moz-do-not-send="true">sblotner59@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">I agree that a survey could be helpful.
<div><br>
</div>
<div>Anecdotally, where I've worked most engineers
prefer Markdown. </div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Mon, Jul 15, 2019
at 6:59 AM Erin McKean <<a
href="mailto:emckean@google.com" target="_blank"
moz-do-not-send="true">emckean@google.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">It sounds like a high-value task might
be doing a survey around what developers (as opposed
to professional technical writers) prefer, since
they are our target audience ... :)
<div><br>
</div>
<div>I agree with Jennifer's point that people who
prefer RST or AsciiDoc are more used to doing
conversions than the other way around. I am
strongly in favor of markdown (in any flavor) for
this reason.</div>
<div><br>
</div>
<div>Erin</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Mon, Jul 15,
2019 at 6:55 AM Jennifer Rondeau <<a
href="mailto:jennifer.rondeau@gmail.com"
target="_blank" moz-do-not-send="true">jennifer.rondeau@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">I'm inclined to agree with Jo's
recommendation of markdown also, at least for
content that we don't publish directly on the
WtD website.
<div><br>
</div>
<div>BUT Felicity asked about data for use of
lightweight markup languages -- to the best of
my somewhat but not entirely limited
knowledge, there isn't real data, only folk
wisdom that developers prefer markdown because
it's simpler. But every time I've seen that
proposition articulated, devs come out of the
woodwork protesting that no, they want to use
only the most appropriate tool and are happy
to switch to something else. That's been my
direct experience as well, but YMMV.</div>
<div><br>
</div>
<div>That said, we've got not much more than
folk wisdom to go on, hence my recommendation
of markdown. I also think that if we deliver
templates in markdown (which we'll need to
mark up specially for them to render in the
browser anyway -- see inter alia the templates
for the Kubernetes docs, at <a
href="https://github.com/kubernetes/website/blob/master/content/en/docs/contribute/style/page-templates.md"
target="_blank" moz-do-not-send="true">https://github.com/kubernetes/website/blob/master/content/en/docs/contribute/style/page-templates.md</a>),
people accustomed to working in rST or
AsciiDoc will be more adept at translating
into their preferred markup language than the
other way around. We could also skip the
rendering-markdown-literally approach to
templates.</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Mon, Jul
15, 2019 at 9:25 AM Jo Cook <<a
href="mailto:jo.k.cook@gmail.com"
target="_blank" moz-do-not-send="true">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">
<div>HI All,</div>
<div><br>
</div>
<div>I'm in favour of keeping things as
simple as possible, for long term
maintenance and for lowering the barrier
for potential contributors. I think also
that we need to be clear whether we're
talking about the format of the files we
use to build the website (which I guess
includes the documentation on best
practices) and the format that we provide
the templates in. <br>
</div>
<div><br>
</div>
<div>I've got experience of both markdown
and rst in both respects, and I think
there are pros and cons to both, but all
things being equal, I'd tend to choose
markdown for the simplicity of the format.
I'm a big fan of the markdown ->
gh-pages approach for collaborative
websites- it's what we use for <a
href="http://uk.osgeo.org"
target="_blank" moz-do-not-send="true">uk.osgeo.org</a>
and it works really well for that where
there's a distributed team of around 15
people with committing rights and varying
levels of technical experience. <br>
</div>
<div><br>
</div>
<div>All the best</div>
<div><br>
</div>
<div>Jo<br>
</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On Mon,
Jul 15, 2019 at 1:42 AM Felicity Brand
<<a
href="mailto:felicitybrand@gmail.com"
target="_blank" moz-do-not-send="true">felicitybrand@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">
<div>Lots of food for thought here!</div>
<div><br>
</div>
Are there any stats on usage/most
popular languages? Just curious.
<div><br>
</div>
<div>Then we could rely on stats to
choose one option to launch with, and
be reactive when folks say something
like "this is great but I wish it was
in AsciiDoc".</div>
<div><br>
</div>
<div>We can be poised with a plan to
build out into other
languages/formats.</div>
<div><br>
</div>
<div>Also, are there converters? </div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On
Mon, Jul 15, 2019 at 8:30 AM Cameron
Shorter <<a
href="mailto:cameron.shorter@gmail.com"
target="_blank"
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 dir="ltr">Thanks Jennifer,
<div>Ideally, TheGoodDocsProject
writers shouldn't have to worry
about formats and tools. My
preference is to highlight that we
have a problem with the limited
options to date, find a
workaround, and park the problem
hoping that some techies will step
up and solve it for us. </div>
<div><br>
</div>
<div>I'm mildly in favour of using
RST with git to start with. Of
note, the workflow that I"m seeing
emerging has been RST -> HTML
-> Google Doc (+Spell/Grammer
Checkers+Grammerly) -> Google
Doc + Review comments and track
changes -> RST.</div>
<div>I suspect this might be our
best option to date. It is messy
and I'm hoping we can find
something better in the long term.</div>
</div>
<br>
<div class="gmail_quote">
<div dir="ltr" class="gmail_attr">On
Mon, 15 Jul 2019 at 01:22,
Jennifer Rondeau <<a
href="mailto:jennifer.rondeau@gmail.com"
target="_blank"
moz-do-not-send="true">jennifer.rondeau@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>Cameron asked me to follow
up on my comment at the end of
our last video conference
about the fact that the Write
the Docs website publishes
with Sphinx -- using Read the
Docs, which in case anybody
isn't familiar is also Eric's
project -- from mostly
reStructuredText format in the
repository (there's still some
markdown, but much of it has
been moved over to rST).</div>
<div><br>
</div>
<div>I mentioned the WtD
toolchain because Erin's also
mentioned Docsy, which is Hugo
and therefore requires
markdown. We've also discussed
templates, but not really
mentioned a markup language
for said templates (unless
I've missed something, which
is a distinct possibility
:-)).</div>
<div><br>
</div>
<div>It's my hope that we can
find a way to provide tools,
templates, and best practices
guides without requiring
consumers of our efforts to
focus on the markup language.
Within the WtD community,
there's considerable interest
in AsciiDoc as well as rST and
Markdown.</div>
<div><br>
</div>
<div>But I don't have definite
ideas about how to address the
situation -- at least not yet.
The only way forward I see *at
the moment* -- while we figure
out solutions -- is to work in
Markdown in one of the repos
in the Good Docs Project GH
org, probably the structure
repo.</div>
<div><br>
</div>
<div>Some fragments/thoughts
about parts of how we might
proceed (nothing mutually
exclusive or complete):</div>
<div>
<ul>
<li>keep some of our content
and templates in TGDP repo
and publish to HTML that
we can incorporate into
the WtD website </li>
<li>write wrapper rST
content in the /guide
directory in the WtD repo</li>
<li>write most of our
content in rST in the WtD
/guide directory but point
to other resources that we
also maintain (as well as
resources we don't
maintain?)</li>
<li>build a sample Docsy
project in a separate repo
that demonstrates specific
Hugo/markdown best
practices (although I
think the Docsy project
already has a fair amount
of this worked out -- but
we could build on it and
point back to TGDP pages)</li>
<li>do something similar to
the previous item for
AsciiDoc/Asciidoctor (get
someone heavily involved
in this community to
contribute here -- or we
could point to analogous
resources elsewhere)</li>
<li>produce templates
written in all three
lightweight markup
languages (with
appropriate gotchas for
differences, including
differences in flavors of
Markdown)</li>
<li>Produce SSG-specific
variants on templates
(this is a variation on
the previous item)</li>
</ul>
<div>I ... think that's enough
for now. I hope it's enough
to show primarily why I
raised the issue this early
in the project, and I hope
it helps everybody who's
interested continue to
brainstorm about how we want
to move forward.</div>
</div>
<div><br>
</div>
<div>See you all online/in
video!</div>
<div><br>
</div>
<div>Jennifer</div>
</div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a
href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank"
moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank"
moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
<br clear="all">
<div><br>
</div>
-- <br>
<div dir="ltr"
class="gmail-m_-8378235529590541185gmail-m_-2035789580350894094gmail-m_7270525336669011188gmail-m_-5575267923567327351gmail-m_-7107784977501501363gmail-m_-5247578663170666986gmail-m_3906849870698562042gmail-m_-6785989406947888012gmail_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>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a
href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank"
moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank"
moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a
href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank" moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank"
moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
<br clear="all">
<br>
-- <br>
<div dir="ltr"
class="gmail-m_-8378235529590541185gmail-m_-2035789580350894094gmail-m_7270525336669011188gmail-m_-5575267923567327351gmail-m_-7107784977501501363gmail-m_-5247578663170666986gmail_signature">------------------------<br>
<a href="http://about.me/jocook"
target="_blank" moz-do-not-send="true">http://about.me/jocook</a></div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank" moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank"
moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank" moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank"
moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
<br clear="all">
<div><br>
</div>
-- <br>
<div dir="ltr"
class="gmail-m_-8378235529590541185gmail-m_-2035789580350894094gmail-m_7270525336669011188gmail-m_-5575267923567327351gmail_signature">
<div dir="ltr">
<div>
<div dir="ltr">
<div
style="line-height:1.5em;padding-top:10px;margin-top:10px;color:rgb(85,85,85);font-family:sans-serif"><span
style="border-width:2px 0px
0px;border-style:solid;border-color:rgb(213,15,37);padding-top:2px;margin-top:2px">Erin
McKean |</span><span
style="border-width:2px 0px
0px;border-style:solid;border-color:rgb(51,105,232);padding-top:2px;margin-top:2px"> Developer
Relations Program Manager, Open Source
Strategy |</span><span
style="border-width:2px 0px
0px;border-style:solid;border-color:rgb(0,153,57);padding-top:2px;margin-top:2px"> <a
href="mailto:emckean@google.com"
target="_blank" moz-do-not-send="true">emckean@google.com</a> |</span><span
style="border-width:2px 0px
0px;border-style:solid;border-color:rgb(238,178,17);padding-top:2px;margin-top:2px"> she/her</span></div>
<br>
</div>
</div>
</div>
</div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank" moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank"
moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
<br clear="all">
<div><br>
</div>
-- <br>
<div dir="ltr"
class="gmail-m_-8378235529590541185gmail-m_-2035789580350894094gmail_signature">
<div dir="ltr">
<div>Stephanie Blotner</div>
<div><br>
</div>
</div>
</div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org"
target="_blank" moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank" moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
_______________________________________________<br>
SeasonOfDocs mailing list<br>
<a href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank"
moz-do-not-send="true">SeasonOfDocs@lists.osgeo.org</a><br>
<a
href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs"
rel="noreferrer" target="_blank" moz-do-not-send="true">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a><br>
</blockquote>
</div>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<pre class="moz-quote-pre" wrap="">_______________________________________________
SeasonOfDocs mailing list
<a class="moz-txt-link-abbreviated" href="mailto:SeasonOfDocs@lists.osgeo.org">SeasonOfDocs@lists.osgeo.org</a>
<a class="moz-txt-link-freetext" href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a>
</pre>
</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>