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

[Clarence Cromwell]

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