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

Sanket Totewar sanket at totewar.com
Sun Jul 21 19:11:14 PDT 2019 

+1 Sanket

On Mon, Jul 22, 2019 at 7:48 AM Jennifer Rondeau <jennifer.rondeau at gmail.com>
wrote:

> +1
>
> On Sun, Jul 21, 2019 at 5:00 PM Felicity Brand <felicitybrand at gmail.com>
> wrote:
>
>> +1
>>
>> On 22 Jul 2019, at 4:34 am, Stephanie Blotner <sblotner59 at gmail.com>
>> wrote:
>>
>> +1
>>
>> On Sun, Jul 21, 2019 at 10:41 AM Jo Cook <jo.k.cook at gmail.com> wrote:
>>
>>> 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
>>> _______________________________________________
>>> SeasonOfDocs mailing list
>>> SeasonOfDocs at lists.osgeo.org
>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>
>>
>>
>> --
>> Stephanie Blotner
>>
>> _______________________________________________
>> SeasonOfDocs mailing list
>> SeasonOfDocs at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
>> _______________________________________________
>> SeasonOfDocs mailing list
>> SeasonOfDocs at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190722/2148f67d/attachment-0001.html>

More information about the SeasonOfDocs mailing list