On Thu, 17 May 2018 15:03:23 +0000 Jeremy Stanley <fu...@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 <fu...@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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
