[Lexicon] [SeasonOfDocs] Starter Style Guide - and Lexicon
Cameron Shorter
cameron.shorter at gmail.com
Sun May 3 14:39:08 PDT 2020
[Looping in the OSGeo Lexicon committee, Reese, Ronald and Rob Atkinson who
have been thinking hard about managing lexicons.]
Alyssa,
Thanks so much for expanding on your ideas here. I think you are unpacking
some really valuable ideas. I'll focus just on lexicon in this email, and
cover your other points in a separate thread.
As part of the Open Source Geospatial Foundation's (OSGeo) involvement in
Season of Docs 2019, we discovered there was a gap in management of
terminology across the 50 or so projects we represented. Further, this is
not just a problem with our geospatial terms, but with cross-project
management of term definitions in general. In reaching into our community
for help, we found Ron, Reese, Rob and others, who are linked with the Open
Geospatial Standards (OGC) community, as well as ISO. I've been really
impressed with their thought leadership in this area. Highlights include:
* Open source software for managing terms.
* ISO standards for how you write a term.
* Thinking about how you can manage cascading points of truth to terms.
* Translating terms between languages.
Rob, Ron, Reese,
I'd be interested to hear you contributions into this thread.
More info:
* https://wiki.osgeo.org/wiki/Lexicon_Committee
* Proposed procedures for drafting terms:
https://docs.google.com/document/d/1s3mnlXc7E41olpqSO24x7c_sfg4UtZSHy-r7xnJfNOw/edit#heading=h.gjdgxs
On Mon, 4 May 2020 at 00:34, Alyssa Rock <arock at saltstack.com> wrote:
> Yes, I think I just didn't fully clarify what this style guide template
> would entail. If it's easier, I can create a proof of concept template for
> this to help you see what I mean.
>
> In my mind, the template for a style guide would look roughly like this:
>
> - Introduction that explains how to use the guide and includes style
> guide highlights (this is the Quick Start for the guide)
> - A quick paragraph about which general style guide you defer to for
> questions that aren't addressed in your guide (Google Developers, Microsoft
> Manual of Style, etc.)
> - A table with an alphabetized word list (glossary) that has three
> columns: Preferred term, Avoid these terms, Explanation and examples
> - A section for topic type definitions with links to the templates
> that should be used for each topic
> - A section for general writing tips (this can be boilerplate because
> these principles are generally universal)
> - An optional revision history that indicates when the guide was last
> revised
>
> Reasons why it's useful to have an in-house style guide in addition to a
> general one:
>
> - You can use it to provide general guidance and instruction about
> writing for new contributors to your project. (Such as the writing tips
> that are already in the repo.) It's not mandatory that new contributors
> read it, but it can provide guidance to them if they do. And it can be a
> reference point if you are mentoring a new contributor. It's just another
> element of quality control.
> - Every project has terms and concepts that are unique to that
> project. (For example, in a past job I held we had a term called "picklist"
> to refer to a UI element that was unique to our software.) Debates are
> always going to arise about how to refer to those terms in the context of
> your documentation. ("Should it be capitalized? Should it be hyphenated?")
> Not every contributor is part of the discussion when these debates are
> settled and so it's helpful to record the conclusion of those debates in
> your style guide, such as in the word list I've suggested. Then when new
> contributors come in and raise those debates again, you can just point them
> to the style guide and say, "We've already resolved this. See the result of
> this debate here in the word list on our style guide. Moving on." Your word
> list doesn't have to be comprehensive when first starting out, but if you
> have a place to record them as you go, it can scale with your project as
> those debates arrive.
> - When you're evaluating the documentation in a PR, you can use the
> style guide to ensure they're following your guidelines. If you're
> evaluating a PR where the documentation isn't of high quality, you then
> have a document that you can refer them to and say: read this section to
> get yourself up to speed in lieu of holding a meeting or typing out a long
> explanation in a PR.
> - Your style guide can be a place where your templates live and where
> you provide examples of "good" and "bad" usage of that template. It's
> guidance for your contributors.
> - What if your org doesn't use the Google Developer's Style Guide as
> your default? What if you want to use Microsoft's Manual of Style? If you
> can indicate and link to the style guide you use as your default style
> guide, that provides some guidance to your contributors.
>
> FYI, one of the reasons this is on my mind is because my current project
> with my Open Salt Documentation working group is to improve our style guide
> to provide more guidance to our contributors when they create documentation
> for new modules. We're a slightly more mature open source project, but it's
> been the Wild West up to this point and it would have been nice if the
> style guide had been used earlier. It creates technical debt to
> retroactively fix your documentation to ensure consistency after the fact
> rather than from the start. A small, in-house style guide can help.
>
> --Alyssa
>
> On Sun, May 3, 2020 at 12:56 AM Felicity Brand <felicitybrand at gmail.com>
> wrote:
>
>> Our project is so meta that I think we can get confused ourselves with
>> what we're talking about. Cameron and Jared, I interpreted Alyssa's
>> message differently.
>>
>> I think what Alyssa is suggesting, and I agree, is that our project
>> could provide a template for a style guide. I have often been required
>> to start an in-house style guide from scratch and would have benefited
>> from a boilerplate. So, just as The Good Docs might provide a template
>> for a ReadMe or API reference, we could provide a template for a style
>> guide.
>>
>> There are certain headings/sections that in-house (or per-project)
>> guides usually have, and we can lay those out. Style guides are
>> usually hierarchical, so as Alyssa suggests, it may begin with "We
>> defer to XYZ's style guide" and then have word lists, spelling guides,
>> punctuation conventions, etc.
>>
>> It's not creating a style to compete with Google or MS, it's about
>> creating a document with headings for a project to populate about how
>> the language in the docs for that project should be.
>>
>> On Sun, May 3, 2020 at 12:56 PM Jared Morgan <jaredleonmorgan at gmail.com>
>> wrote:
>> >
>> > -1 to creating our own style. -1 even to making an override document
>> that links out to variations from an existing style guide.
>> >
>> > In short the Google style guide is our "standard" and there is a
>> background to this.
>> >
>> > If down the track we want to introduce the concept of docs linting
>> (validation of docs using tools like Vale) this style guide is compatible
>> with that tool.
>> >
>> > Another reason is that Google dev guide is also well understood by
>> developers so there will be less onboarding required with this guide than
>> others.
>> >
>> > If you feel the tips for writing contradict the guidance in the tips
>> for writing we can look further into it.
>> >
>> >
>> > On Sun, 3 May 2020, 08:18 Cameron Shorter, <cameron.shorter at gmail.com>
>> wrote:
>> >>
>> >> Moving suggestion from Alyssa onto an email thread, so it doesn't get
>> lost...
>> >>
>> >> Alyssa 3:14 AM
>> >> I've noticed that we currently don't have an official template for a
>> starter style guide (although the Writing Tips template does have this kind
>> of content). In my experience, it's sometimes helpful to start out with a
>> bare-bones or boilerplate style guide that your core contributors can just
>> add to here and there as consistency issues arrive. Even if the guide is as
>> simple as "We defer to XYZ's style guide: <link>" + a word list for how to
>> refer to terms that are specific to the project. Would anyone have
>> objections to me perhaps adapting/expanding the Writing Tips template to
>> become a bare bones/boilerplate style guide? No worries if you think this
>> is a bad idea. Feel free to discuss!
>> >>
>> >> Hi Alyssa, I like your suggestion and would be happy with you starting
>> on this.
>> >> With regards to the full writing domain, I think that you can separate
>> out document structure from style. And to date I believe we have aimed to
>> focus and get really good at one thing (namely templates and doc structure)
>> rather than be average at lots of things.
>> >> I'd be hesitant to go creating a new style, and suggest that we refer
>> people to existing mature style guides. To date, we have pointed people to
>> Google's developer documentation style guide,
>> https://developers.google.com/style. However, I would anticipate
>> different communities plugging in a separate guide.
>> >> Google also has tech writer training which I think we should lever and
>> align with. Linked from https://developers.google.com/tech-writing
>> >> I'd be interested to hear your thoughts on this approach?
>> >> I'd also be interested to hear Jared's thoughts on whether the writing
>> tips he wrote should be extended, or whether it should be approached
>> separately.
>> >>
>> >> Cheers,
>> >> --
>> >> Cameron Shorter
>> >> Technology Writer at Google
>> >>
>> >> M +61 (0) 419 142 254
>> >>
>> >>
>> >>
>> > _______________________________________________
>> > SeasonOfDocs mailing list
>> > SeasonOfDocs at lists.osgeo.org
>> > https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
>
--
Cameron Shorter
Technology Writer at Google
Open Technologies and Geospatial Evangelist
M +61 (0) 419 142 254
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/lexicon/attachments/20200504/a593d50d/attachment.html>
More information about the Lexicon
mailing list