[SeasonOfDocs] formats, tools, workflows

Mon Jul 15 06:24:30 PDT 2019

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