<div dir="ltr">Whoops, I seem incapable of writing a complete email this morning. The only conversion tool I'm aware of is pandoc and I'm not sure of its reliability in this case.</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Jul 15, 2019 at 9:56 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">Also, I don't think this should be a blocking issue. Pick one, go from there. Jo and Cameron can discuss the md vs rst question further :D</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Jul 15, 2019 at 9: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>
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_-8161249967601985531gmail-m_-3588243296006655856gmail-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">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><br clear="all"><br>-- <br><div dir="ltr" class="gmail-m_-8161249967601985531gmail-m_-3588243296006655856gmail-m_-5247578663170666986gmail_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>
</blockquote></div>
</blockquote></div>