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

Sun Aug 11 14:20:55 PDT 2019

I’d have a lot to say if the alternatives were the Microsoft guide and something like the Chicago Manual of style, which lacks specific advice about formatting code samples and writing an API reference section.

The Google and Microsoft guides are closer together because they’re both pretty good. And a decision over which guide is better would have to get into the nitty gritty details of their specific advice on documenting code — except that might not be necessary because we’re creating a website that might not have a lot of code examples. 

I think we might be okay with either guide, but I’d like to know whether anybody is going to express strong feelings for or against at this point. 

If not, we can resort to a coin flip. 

Sent from my iPhone

> On Aug 11, 2019, at 1:49 PM, 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
> 
> 
> 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/seasonofdocs/attachments/20190811/0d763898/attachment-0001.html>