[SeasonOfDocs] Not a Motion Yet: adopt a style guide
Cameron Shorter
cameron.shorter at gmail.com
Mon Aug 12 13:13:00 PDT 2019
Sharing Sarah's response, with permission ...
On 12/8/19 9:07 am, Sarah Maddox wrote:
> Hallo Cameron
>
> I think it'd be fine for The Good Docs Project to list a few
> recommended style guides and let people choose the one that suits
> their use case best. The most important thing is consistency within a
> doc set, to give readers a smooth ride through the text. I don't think
> we can aim for consistency across all open source doc sets.
>
> I'd like to know what others think!
>
> Cheers
> Sarah
On 12/8/19 1:20 pm, Clarence Cromwell wrote:
>
> 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
> <mailto: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 <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 <mailto: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
>> <mailto: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
>> <mailto: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
>> <mailto: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
>>> <mailto: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
>>> <mailto: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
>>>> <mailto: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
>>>> <mailto:SeasonOfDocs at lists.osgeo.org>
>>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>>
>>>>
>>>>
>>>> --
>>>> Stephanie Blotner
>>>>
>>> _______________________________________________
>>> SeasonOfDocs mailing list
>>> SeasonOfDocs at lists.osgeo.org
>>> <mailto:SeasonOfDocs at lists.osgeo.org>
>>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>>
>>>
>>> _______________________________________________
>>> SeasonOfDocs mailing list
>>> SeasonOfDocs at lists.osgeo.org <mailto: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
>> <mailto:SeasonOfDocs at lists.osgeo.org>
>> https://lists.osgeo.org/mailman/listinfo/seasonofdocs
>>
>> _______________________________________________
>> SeasonOfDocs mailing list
>> SeasonOfDocs at lists.osgeo.org
>> <mailto: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 <mailto: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/20190813/3bff4562/attachment-0001.html>
More information about the SeasonOfDocs
mailing list