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

Sun Jul 21 11:34:28 PDT 2019

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