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

Stefano Canepa sc at linux.it
Mon May 28 15:46:47 UTC 2018

On 28 May 2018 at 15:40, Petr Kovar <pkovar at redhat.com> wrote:

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


> 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

​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¢

PS: a good free doc style guideline is the gnome one.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180528/23cbfe29/attachment.html>

More information about the OpenStack-dev mailing list