[SeasonOfDocs] Starter Style Guide

[Cameron Shorter]

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/22815fdf/attachment.html>