[openstack-dev] [docs] Style guide for OpenStack documentation

Petr Kovar pkovar at redhat.com
Thu May 17 14:35:36 UTC 2018

On Wed, 16 May 2018 17:05:15 +0000
Jeremy Stanley <fungi at yuggoth.org> wrote:

> On 2018-05-16 18:24:45 +0200 (+0200), Petr Kovar wrote:
> [...]
> > I'd like to propose replacing the reference to the IBM Style Guide
> > with a reference to the developerWorks editorial style guide
> > (https://www.ibm.com/developerworks/library/styleguidelines/).
> > This lightweight version comes from the same company and is based
> > on the same guidelines, but most importantly, it is available for
> > free.
> [...]
> I suppose replacing a style guide nobody can access with one
> everyone can (modulo legal concerns) is a step up. Still, are there
> no style guides published under an actual free/open license? If
> https://www.ibm.com/developerworks/community/terms/use/ is correct
> then even accidental creation of a derivative work might be
> prosecuted as copyright infringement.

We don't really plan on reusing content from that site, just referring to
it, so is it a concern?

> http://www.writethedocs.org/guide/writing/style-guides/#selecting-a-good-style-guide-for-you
> mentions some more aligned with our community's open ideals, such as
> the 18F Content Guide (public domain), SUSE Documentation Style
> Guide (GFDL), GNOME Documentation Style Guide (GFDL), and the
> Writing Style Guide and Preferred Usage for DOD Issuances (public
> domain). Granted adopting one of those might lead to a need to
> overhaul some aspects of style in existing documents, so I can
> understand it's not a choice to be made lightly. Still, we should
> always consider embracing open process, and that includes using
> guidelines which we can freely derive and republish as needed.

I would be interested in hearing what other people think about that, but I
would strongly prefer to stick with the existing "publisher" as that creates
fewer issues than switching to a completely different style guide and
then having to adjust our guidelines based on the IBM guide, etc.


More information about the OpenStack-dev mailing list