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

Jeremy Stanley fungi at yuggoth.org
Thu May 17 15:03:23 UTC 2018

On 2018-05-17 16:35:36 +0200 (+0200), Petr Kovar wrote:
> 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?

A style guide is a tool. Free and open collaboration needs free
(libre, not merely gratis) tools, and that doesn't just mean
software. If, down the road, you want an OpenStack Documentation
Style Guide which covers OpenStack-specific concerns to quote or
transclude information from a more thorough guide, that becomes a
derivative work and is subject to the licensing terms for the guide
from which you're copying.

There are a lot of other parallels between writing software and
writing prose here beyond mere intellectual property concerns too.
Saying that OpenStack Documentation is free and open, but then
endorsing an effectively proprietary guide as something its authors
should read and follow, sends a mixed message as to our position on
open documentation (as a style guide is of course also documentation
in its own right). On the other hand, recommending use of a style
guide which is available under a free/libre open source license or
within the public domain resonates with our ideals and principles as
a community, serving only to strengthen our position on openness in
all its endeavors (including documentation).
Jeremy Stanley
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 963 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180517/85766ac5/attachment.sig>

More information about the OpenStack-dev mailing list