[SeasonOfDocs] formats, tools, workflows

Mon Jul 15 06:57:32 PDT 2019

Whoops, I seem incapable of writing a complete email this morning. The only
conversion tool I'm aware of is pandoc and I'm not sure of its reliability
in this case.

On Mon, Jul 15, 2019 at 9:56 AM Jennifer Rondeau <jennifer.rondeau at gmail.com>
wrote:

> Also, I don't think this should be a blocking issue. Pick one, go from
> there. Jo and Cameron can discuss the md vs rst question further :D
>
> On Mon, Jul 15, 2019 at 9: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
>>>>>> _______________________________________________
>>>>>> SeasonOfDocs mailing list
>>>>>> SeasonOfDocs at lists.osgeo.org
>>>>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> 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
>>>>>
>>>> _______________________________________________
>>>> 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
>>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190715/b20c5f45/attachment-0001.html>