[SeasonOfDocs] Starter Style Guide

Alyssa Rock arock at saltstack.com
Sun May 3 07:34:02 PDT 2020 

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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20200503/1ee72a02/attachment.html>

More information about the SeasonOfDocs mailing list