<div dir="ltr"><div class="gmail_default" style="font-family:verdana,sans-serif">+1 Sanket<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Jul 22, 2019 at 7:48 AM Jennifer Rondeau <<a href="mailto:jennifer.rondeau@gmail.com">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">+1<br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Jul 21, 2019 at 5:00 PM Felicity Brand <<a href="mailto:felicitybrand@gmail.com" target="_blank">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="auto"><div dir="ltr"></div><div dir="ltr">+1</div><div dir="ltr"><br>On 22 Jul 2019, at 4:34 am, Stephanie Blotner <<a href="mailto:sblotner59@gmail.com" target="_blank">sblotner59@gmail.com</a>> wrote:<br><br></div><blockquote type="cite"><div dir="ltr"><div dir="ltr">+1<br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Jul 21, 2019 at 10:41 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"><div>Seconded and +1 from Jo</div><div><br></div><div>Jo<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Jul 21, 2019 at 11:56 AM 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>To bring this email thread to a decision, I put forward the
following motion, <br>
</p>
<p><b>Motion: As we start developing content for
WriteTheDocsProject, our target format will be Markdown.</b></p>
<p>My vote: +1 Cameron</p>
<p>--<br>
</p>
<p>This is based on my read of our rough consensus:</p>
<p>* The focus of our project is to create content rather than
formats.</p>
<p>* We should pick an initial format to start with, with the long
term goal of supporting multiple formats.</p>
<p>* Markdown seems to be the preferred format from our community
here.</p>
<p>* We could change formats some time in the future. <br>
</p>
<p>* Some suggestions of setting up a survey, but I'm not sure we
have built a large enough community to engage meaningfully with a
survey.</p>
<p>--<br>
</p>
<p>I'll hold this motion open until our weekly meeting this week.</p>
<p>--</p>
<p>Voting is as per: <a href="https://github.com/thegooddocs/governance/blob/master/ProjectSteeringCommittee.rst" target="_blank">https://github.com/thegooddocs/governance/blob/master/ProjectSteeringCommittee.rst</a></p>
<ul>
<li style="box-sizing:border-box">+1 : For</li>
<li style="box-sizing:border-box;margin-top:0.25em">+0: Mildly
for, but mostly indifferent</li>
<li style="box-sizing:border-box;margin-top:0.25em">0:
Indifferent</li>
<li style="box-sizing:border-box;margin-top:0.25em">-0: Mildly
against, but mostly indifferent</li>
<li style="box-sizing:border-box;margin-top:0.25em">-1 :
Strongly against. This is expected to be accompanied by a
reason.</li>
</ul>
<p>Project Steering Committee member votes count. (I hope to make
this committee official in the same timeframe).<br>
Votes and opinions from others will be considered.<br>
</p>
<div class="gmail-m_9129859766419085151gmail-m_838389382900245046gmail-m_-8569089410097799770gmail-m_7038792061389417330moz-cite-prefix">On 16/7/19 1:58 am, Eric Holscher
wrote:<br>
</div>
<blockquote type="cite">
<div dir="ltr">I'd probably stick with markdown. We can pretty
easily support it in the WTD repos and most tools can convert md
to other formats if needed, since it's one of the more simple
ones. I'd really try and stick to commonmark though, and not any
of the advanced flavors, so you don't hit issues with
conversion.
<div><br>
</div>
<div>I don't think this content is complex enough that you'll
need much in the way of the advanced features of RST/Adoc. If
you do, you can cross that bridge when you get there. </div>
<div>
<div><br>
</div>
<div>Cheers,</div>
<div>Eric</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">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">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">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">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">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">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">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">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">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>
</blockquote>
</div>
</blockquote>
</div>
</blockquote>
</div>
</blockquote>
</div>
</blockquote>
</div>
</blockquote>
</div>
</blockquote>
</div>
</blockquote>
<pre class="gmail-m_9129859766419085151gmail-m_838389382900245046gmail-m_-8569089410097799770gmail-m_7038792061389417330moz-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><br clear="all"><br>-- <br><div dir="ltr" class="gmail-m_9129859766419085151gmail-m_838389382900245046gmail-m_-8569089410097799770gmail_signature">------------------------<br><a href="http://about.me/jocook" target="_blank">http://about.me/jocook</a></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><br clear="all"><div><br></div>-- <br><div dir="ltr" class="gmail-m_9129859766419085151gmail-m_838389382900245046gmail_signature"><div dir="ltr"><div>Stephanie Blotner</div><div><br></div></div></div>
</div></blockquote><blockquote type="cite"><div dir="ltr"><span>_______________________________________________</span><br><span>SeasonOfDocs mailing list</span><br><span><a href="mailto:SeasonOfDocs@lists.osgeo.org" target="_blank">SeasonOfDocs@lists.osgeo.org</a></span><br><span><a href="https://lists.osgeo.org/mailman/listinfo/seasonofdocs" target="_blank">https://lists.osgeo.org/mailman/listinfo/seasonofdocs</a></span><br></div></blockquote></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>
_______________________________________________<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>