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

Sun Jul 21 14:48:23 PDT 2019

+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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190721/902a99a5/attachment-0001.html>