Re: [openstack-dev] [docs] Style guide for OpenStack documentation
On 2018-05-28 16:40:13 +0200 (+0200), Petr Kovar wrote: [...] > 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. [...] I get this (and alluded to as much in my first message in this thread, in fact). My point was that _when_ you're to the point of evaluating switching to a wholly different style guide it would be great to take such concerns into account. It also serves as a cautionary tale to other newly forming projects (outside OpenStack) who may at some point stumble across this discussion. Please choose free tools at every opportunity, I sure wish we had in this case. -- Jeremy Stanley signature.asc Description: PGP signature __ 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
Re: [openstack-dev] [docs] Style guide for OpenStack documentation
On 28 May 2018 at 15:40, Petr Kovar wrote: > On Thu, 17 May 2018 15:03:23 + > Jeremy Stanley wrote: > > > On 2018-05-17 16:35:36 +0200 (+0200), Petr Kovar wrote: > %<- > 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 > Petr, do we really need to reference to another style guide? How many times people clicked on the link to the IBM guide? If first answer is yes and second is hundreds of times than in my opinion you first option is the right one otherwise I'd go for the second. My 2¢ Stefano PS: a good free doc style guideline is the gnome one. __ 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
Re: [openstack-dev] [docs] Style guide for OpenStack documentation
On Thu, 17 May 2018 15:03:23 + Jeremy Stanley wrote: > On 2018-05-17 16:35:36 +0200 (+0200), Petr Kovar wrote: > > On Wed, 16 May 2018 17:05:15 + > > Jeremy Stanley 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
Re: [openstack-dev] [docs] Style guide for OpenStack documentation
On 2018-05-17 16:35:36 +0200 (+0200), Petr Kovar wrote: > On Wed, 16 May 2018 17:05:15 + > Jeremy Stanley 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 signature.asc Description: PGP signature __ 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
Re: [openstack-dev] [docs] Style guide for OpenStack documentation
On Wed, 16 May 2018 17:05:15 + Jeremy Stanley 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. Thanks, 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
Re: [openstack-dev] [docs] Style guide for OpenStack documentation
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. 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. -- Jeremy Stanley signature.asc Description: PGP signature __ 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
