[SeasonOfDocs] formats, tools, workflows
Cameron Shorter
cameron.shorter at gmail.com
Tue Jul 16 14:27:12 PDT 2019
Love your ideas Clarence.
I particularly like your concept of a "Minimal Viable Docset".
Yes, I'd encourage you to start sketching out ideas for templates, and
starting to define personas of our target audiences.
Probably start by adding ideas into Jo's Project Structure doc:
https://docs.google.com/document/d/1u656sQLSH5JspMvYqjuZuyCVTVwgIqisnyA6NO5AUgQ/edit
On 16/7/19 7:05 am, Jennifer Rondeau wrote:
> +1000 to everything Clarence says here :D
>
> On Mon, Jul 15, 2019 at 3:59 PM Clarence Cromwell
> <clarencewcromwell at gmail.com <mailto: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:
> 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 <mailto: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 <mailto: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
> <mailto: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 <mailto: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 <http://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
> <mailto: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
> <mailto: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
> <mailto: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
> <mailto: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
> <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
>
>
> --
> ------------------------
> http://about.me/jocook
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> <mailto: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
> <mailto:emckean at google.com> | she/her
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org
> <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
>
>
> --
> Stephanie Blotner
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org <mailto:SeasonOfDocs at lists.osgeo.org>
> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>
> _______________________________________________
> SeasonOfDocs mailing list
> SeasonOfDocs at lists.osgeo.org <mailto: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
--
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/20190717/1c958567/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/20190717/1c958567/attachment-0001.png>
More information about the SeasonOfDocs
mailing list