[openstack-dev] [docs] Style guide for OpenStack documentation
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.
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.
PS: a good free doc style guideline is the gnome one.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the OpenStack-dev