[SeasonOfDocs] formats, tools, workflows

Mon Jul 15 14:05:52 PDT 2019

+1000 to everything Clarence says here :D

On Mon, Jul 15, 2019 at 3:59 PM Clarence Cromwell <
clarencewcromwell at gmail.com> wrote:

> On the topic of this survey, I don't understand whether we're talking
> about markup that contributors to this project would use, or the presumed
> language of the end-users for the templates. (Do we need to think about
> markup language of end-users?)
>
> Have we been considering something like a buildable site? That seems
> exponentially more complicated than a literal template.
>
> Along that line of inquiry: What sort of deliverables will this project
> create?
>
> I have been thinking that end users would get the most help from a
> template that looks like a document outline, and that loosely describes
> what ought to be included. That would be platform- and language-agnostic,
> and would focus on the main benefit of this project without getting bogged
> down in a lot of technical questions.
>
> For example:
>
> [image: Screen Shot 2019-07-15 at 11.54.11 AM.png]
> [. . .]
>
> (This example applies to an API, although I know the templates don't have
> to be that specific. It's also in markdown, but I don't see any reason why
> an HTML presentation of the outline wouldn't work.)
>
> In addition to a plain outline, I would also advocate for offering a model
> of a Minimum Viable Docset. I've been talking to people about what is
> included in the MVD when you roll out a new product. I've noticed that
> mature products are frequently lacking key documentation features that
> should have been included in the beginning, and it seems that having a
> checklist of what should be there, would make quite a difference.
>
> (I'm sure the MVD would be slightly different for an API, a cloud-based
> product, and a customer-hosted product.)
>
> I should add that many developers I've talked to at Write the Docs are
> looking for this kind of direction. They want to know what sort of document
> to create and what goes in it, because they need just enough structure to
> send them in the right direction. So an MVD model and a set of document
> outlines would answer most of their questions.
>
> I hope it's not too soon, to dig into the nitty gritty details of
> documentation templates.
>
> Clarence
>
>
>
> On Mon, Jul 15, 2019 at 8:12 AM Stephanie Blotner <sblotner59 at gmail.com>
> wrote:
>
>> I agree that a survey could be helpful.
>>
>> Anecdotally, where I've worked most engineers prefer Markdown.
>>
>> On Mon, Jul 15, 2019 at 6:59 AM Erin McKean <emckean at google.com> wrote:
>>
>>> 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
>>>
>>> _______________________________________________
>>> SeasonOfDocs mailing list
>>> SeasonOfDocs at lists.osgeo.org
>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>
>>
>>
>> --
>> Stephanie Blotner
>>
>> _______________________________________________
>> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190715/ec591122/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: Screen Shot 2019-07-15 at 11.54.11 AM.png
Type: image/png
Size: 64921 bytes
Desc: not available
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190715/ec591122/attachment-0001.png>