Open Stack

On Thu, 17 May 2018 15:03:23 +0000
Jeremy Stanley <fungi at yuggoth.org> wrote:

> 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.

Okay, but that's not what we want to do here.
 
> 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).

I'm all for openness but maintaining consistency is why style guides
matter. Switching to a different style guide would require the following:

1) agreeing on the right style guide,
2) reviewing our current style guidelines in doc-contrib-guide and updating
them as needed so that they comply with the new style guide, and,
3) ideally, begin reviewing all of OpenStack docs for style changes.

Do we have a volunteer who would be interested in taking on these tasks? If
not, we have to go for a quick fix. Either reference developerWorks, or, if
that's a concern, remove references to external style guides
altogether (and provide less information as a result). I prefer the former.

Cheers,
pk