[SeasonOfDocs] Starter Style Guide

[Jared Morgan]

-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 <https://app.slack.com/team/U012KCMPP0V>  3:14 AM
> <https://thegooddocs.slack.com/archives/CQT6T04CW/p1588439680199800>
> I've noticed that we currently don't have an official template for a
> starter style guide (although the Writing Tips
> <https://github.com/thegooddocsproject/templates/blob/master/writing-tips.md>
> 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
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20200503/e84e9daf/attachment.html>