[SeasonOfDocs] formats, tools, workflows

[Felicity Brand]

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