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

Sun Aug 11 20:20:24 PDT 2019

We don’t need to push everyone in the world into one guide, but we need to choose one for internal consistency. 
We shouldn’t be using different spelling rules and comma rules from one another as we contribute to these docs.
I don’t mean to suggest one guide to rule them all.
:-)
I agree with having a list of recommended guides, which should include both of these options.

Sent from my iPhone

> On Aug 11, 2019, at 5:39 PM, Felicity Brand <felicitybrand at gmail.com> wrote:
> 
> 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. 
> 
> 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? 
>>>>>>>> 
>>>>>>>>> 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 and the Merriam-Webster 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 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
>>> _______________________________________________
>>> 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/20190811/9c6bf480/attachment-0001.html>