[SeasonOfDocs] formats, tools, workflows

[Cameron Shorter]

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