[SeasonOfDocs] formats, tools, workflows

Mon Jul 15 06:59:19 PDT 2019

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
>>>>> _______________________________________________
>>>>> 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
>>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>

-- 
Erin McKean | Developer Relations Program Manager, Open Source Strategy |
emckean at google.com | she/her
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190715/5222cd25/attachment-0001.html>