[SeasonOfDocs] formats, tools, workflows: Motion - Use Markdown format (to start with)
Cameron Shorter
cameron.shorter at gmail.com
Sun Jul 21 03:55:54 PDT 2019
To bring this email thread to a decision, I put forward the following
motion,
*Motion: As we start developing content for WriteTheDocsProject, our
target format will be Markdown.*
My vote: +1 Cameron
--
This is based on my read of our rough consensus:
* The focus of our project is to create content rather than formats.
* We should pick an initial format to start with, with the long term
goal of supporting multiple formats.
* Markdown seems to be the preferred format from our community here.
* We could change formats some time in the future.
* 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.
--
I'll hold this motion open until our weekly meeting this week.
--
Voting is as per:
https://github.com/thegooddocs/governance/blob/master/ProjectSteeringCommittee.rst
* +1 : For
* +0: Mildly for, but mostly indifferent
* 0: Indifferent
* -0: Mildly against, but mostly indifferent
* -1 : Strongly against. This is expected to be accompanied by a reason.
Project Steering Committee member votes count. (I hope to make this
committee official in the same timeframe).
Votes and opinions from others will be considered.
On 16/7/19 1:58 am, Eric Holscher wrote:
> 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.
>
> 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.
>
> Cheers,
> Eric
>
> On Mon, Jul 15, 2019 at 8:12 AM Stephanie Blotner
> <sblotner59 at gmail.com <mailto:sblotner59 at gmail.com>> wrote:
>
> I agree that a survey could be helpful.
>
> Anecdotally, where I've worked most engineers prefer Markdown.
>
> On Mon, Jul 15, 2019 at 6:59 AM Erin McKean <emckean at google.com
> <mailto:emckean at google.com>> wrote:
>
> 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 ... :)
>
> 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.
>
> Erin
>
> On Mon, Jul 15, 2019 at 6:55 AM Jennifer Rondeau
> <jennifer.rondeau at gmail.com
> <mailto:jennifer.rondeau at gmail.com>> wrote:
>
> 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.
>
> 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.
>
> 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
> https://github.com/kubernetes/website/blob/master/content/en/docs/contribute/style/page-templates.md),
> 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.
>
> On Mon, Jul 15, 2019 at 9:25 AM Jo Cook
> <jo.k.cook at gmail.com <mailto:jo.k.cook at gmail.com>> wrote:
>
> HI All,
>
> 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.
>
> 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
> uk.osgeo.org <http://uk.osgeo.org> 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.
>
> All the best
>
> Jo
>
> On Mon, Jul 15, 2019 at 1:42 AM Felicity Brand
> <felicitybrand at gmail.com
> <mailto:felicitybrand at gmail.com>> wrote:
>
> Lots of food for thought here!
>
> Are there any stats on usage/most popular
> languages? Just curious.
>
> 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".
>
> We can be poised with a plan to build out into
> other languages/formats.
>
> Also, are there converters?
>
> On Mon, Jul 15, 2019 at 8:30 AM Cameron Shorter
> <cameron.shorter at gmail.com
> <mailto:cameron.shorter at gmail.com>> wrote:
>
> Thanks Jennifer,
> 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.
>
> 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.
> 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.
>
> On Mon, 15 Jul 2019 at 01:22, Jennifer Rondeau
> <jennifer.rondeau at gmail.com
> <mailto:jennifer.rondeau at gmail.com>> wrote:
>
> Hi all,
>
> 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).
>
> 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 :-)).
>
> 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.
>
> 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.
>
> Some fragments/thoughts about parts of how
> we might proceed (nothing mutually
> exclusive or complete):
>
> * keep some of our content and templates
> in TGDP repo and publish to HTML that
> we can incorporate into the WtD website
> * write wrapper rST content in the
> /guide directory in the WtD repo
> * 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?)
> * 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)
> * 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)
> * produce templates written in all three
> lightweight markup languages (with
> appropriate gotchas for differences,
> including differences in flavors of
> Markdown)
> * Produce SSG-specific variants on
> templates (this is a variation on the
> previous item)
>
> 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.
>
> See you all online/in video!
>
> Jennifer
>
--
Cameron Shorter
Technology Demystifier
Open Technologies and Geospatial Consultant
M +61 (0) 419 142 254
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190721/80292bae/attachment-0001.html>
More information about the SeasonOfDocs
mailing list