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

Sun Jul 21 22:20:56 PDT 2019

+1

On Mon, 22 Jul, 2019, 7:41 AM Sanket Totewar, <sanket at totewar.com> wrote:

> +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
>>
> _______________________________________________
> 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/d181a9a2/attachment-0001.html>