[SeasonOfDocs] formats, tools, workflows: Motion - Use Markdown format (to start with)

Sun Jul 21 10:40:54 PDT 2019

Seconded and +1 from Jo

Jo

On Sun, Jul 21, 2019 at 11:56 AM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> 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>
> 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> 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> 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> 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 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> 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> 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> 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
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>

-- 
------------------------
http://about.me/jocook
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190721/de703e3f/attachment-0001.html>