[SeasonOfDocs] Starter Style Guide

[Felicity Brand]

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