[SeasonOfDocs] Not a Motion Yet: adopt a style guide

Sun Aug 11 17:39:55 PDT 2019

I'm not too fussed on which one we choose - but from a selfish perspective
I have recent experience using Microsoft and Apple styles so they are
familiar to me (and it's all about ME).

I think tGDP need to choose a style guide for our own website and templates
that we produce - and explain why we chose it.

I think anything more than that should just be a curated list of style
guides so that folks can choose one appropriate for their context.

The intent of moving them toward a universal guide strikes me as kind of
Orwellian. So I had to smile when I saw that Google has a quote from Orwell on
their page <https://developers.google.com/style/>.

Or perhaps this idea is more like Tolkien? *One style guide to rule them
all.*

I am not convinced that a universal style guide could (or should) ever
exist, because writing totally depends on context.

On Mon, Aug 12, 2019 at 6:49 AM Cameron Shorter <cameron.shorter at gmail.com>
wrote:

> Clarence, others, why would I choose one of the other? You might want to
> answer this question for other guides as well.
> If we were to approach the owners of style guides, such as
> Google/Microsoft/Wikipedia, with the intent of moving them toward a
> universal guide, what should we say to them?
>
> Do the people here have opinions on this? I'm hoping so.
>
> On Mon, 12 Aug 2019 at 04:11, Clarence Cromwell <
> clarencewcromwell at gmail.com> wrote:
>
>> Here are both guides in one place.
>>
>> Google:
>> https://developers.google.com/style/
>>
>> Microsoft:
>> https://docs.microsoft.com/en-us/style-guide/welcome/
>>
>> On Sun, Aug 11, 2019 at 11:00 AM Clarence Cromwell <
>> clarencewcromwell at gmail.com> wrote:
>>
>>>
>>> Both of the guides offer good writing tips and have useful information
>>> about how to document APIs. Does anyone have strong feelings about one
>>> guide or the other?
>>>
>>>
>>>
>>>
>>>
>>> On Wed, Aug 7, 2019 at 1:08 PM Cameron Shorter <
>>> cameron.shorter at gmail.com> wrote:
>>>
>>>> I've change title to "Not a Motion yet". I can see that we have a
>>>> difference of opinions, which is fine. I think this is an important topic
>>>> for a tech writing project, and I would love to see robust and wide
>>>> discussion about it for at least a week, possibly more.
>>>>
>>>> This community is full of tech writers I have a lot of respect for, and
>>>> I'm keen to hear from each of you - even if it is just to say "I don't
>>>> care".
>>>>
>>>> Once we have moved toward "rough consensus" we can then re-raise the
>>>> motion.
>>>>
>>>> For my part, I don't have an opinion yet; my opinion will be formed
>>>> based upon this discussion.
>>>> On 8/8/19 5:06 am, Jennifer Rondeau wrote:
>>>>
>>>> Point of clarification: is this a style guide for the project to follow
>>>> as it develops content, or a style guide to recommend to projects that
>>>> might use tGDP?
>>>>
>>>> The former, I'm somewhat +1 to MS, somewhat -1 to the Google guide.
>>>> Happy to explain if needed.
>>>>
>>>> The latter, I'm -1 on any style guide. The appropriate guidance is the
>>>> kind of thing that the WTD guide already provides (lots of options, with
>>>> explanations of what they are and why they might be appropriate for
>>>> particular contexts/requirements/audiences/projects).
>>>>
>>>> On Wed, Aug 7, 2019 at 2:47 PM Clarence Cromwell <
>>>> clarencewcromwell at gmail.com> wrote:
>>>>
>>>>> That might be a worthy alternative. Is this a motion, and if so, what
>>>>> dictionary would go with it?
>>>>>
>>>>> Sent from my iPhone
>>>>>
>>>>> On Aug 7, 2019, at 11:43 AM, Stephanie Blotner <sblotner59 at gmail.com>
>>>>> wrote:
>>>>>
>>>>> What about the Google Developer Documentation Style Guide
>>>>> <https://developers.google.com/style/>?
>>>>>
>>>>> On Wed, Aug 7, 2019 at 9:20 AM Clarence Cromwell <
>>>>> clarencewcromwell at gmail.com> wrote:
>>>>>
>>>>>> I move that we adopt the Microsoft Style Guide
>>>>>> <https://docs.microsoft.com/en-us/style-guide/welcome/> and the Merriam-Webster
>>>>>> <https://www.merriam-webster.com/>dictionary for The Good Docs
>>>>>> project, and that we apply them to whatever writing is generated by the
>>>>>> project (our web site and our official templates) but that we don't demand
>>>>>> that anyone use a guide for contributing a collection of templates, as they
>>>>>> are source material.
>>>>>>
>>>>>> (I would emphasize that we only have to apply the style guide to
>>>>>> material before we publish it, so that doesn't even require that people
>>>>>> learn it before contributing; anyone who doesn't have the time, could allow
>>>>>> an editor to clean up contributions according to the style guide.)
>>>>>>
>>>>>> Reasoning:
>>>>>>
>>>>>>    - We need to all work from a single standard.
>>>>>>    - These guides are available for free online.
>>>>>>    - The Microsoft Guide is specific to technical writing, and is
>>>>>>    widely accepted in the industry.
>>>>>>
>>>>>> If there are strong feelings about using a different guide, I would
>>>>>> suggest a counter-motion naming a specific set of books, so that people can
>>>>>> vote for one or the other, and then we can get on with business.
>>>>>> _______________________________________________
>>>>>> SeasonOfDocs mailing list
>>>>>> SeasonOfDocs at lists.osgeo.org
>>>>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Stephanie Blotner
>>>>>
>>>>> _______________________________________________
>>>>> SeasonOfDocs mailing list
>>>>> SeasonOfDocs at lists.osgeo.org
>>>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>>>
>>>>
>>>> _______________________________________________
>>>> SeasonOfDocs mailing listSeasonOfDocs at lists.osgeo.orghttps://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>>
>>>> --
>>>> Cameron Shorter
>>>> Technology Demystifier
>>>> Open Technologies and Geospatial Consultant
>>>>
>>>> M +61 (0) 419 142 254
>>>>
>>>> _______________________________________________
>>>> SeasonOfDocs mailing list
>>>> SeasonOfDocs at lists.osgeo.org
>>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>>
>>> _______________________________________________
>> SeasonOfDocs mailing list
>> SeasonOfDocs at lists.osgeo.org
>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
>
>
> --
> Cameron Shorter
> Technology Demystifier
> Open Technologies and Geospatial Consultant
>
> 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/20190812/702675fa/attachment.html>