[OpenStack-docs] Proposal: bold/italics in style guides

Andreas Jaeger aj at suse.com
Tue Nov 11 20:43:59 UTC 2014


On 11/09/2014 04:16 PM, Andreas Jaeger wrote:
> On Friday, a few folks from infra team sat together and discussed the
> style guide for the infra-manual (see
> https://etherpad.openstack.org/p/kilo-infra-manual ) as a followup to
> reviewing : https://review.openstack.org/#/c/107303/  and
> https://review.openstack.org/#/c/107360/ . I took the action item to
> cover the problems as an enhancement to our style guide.
> 
> Looking up the IBM style guide, I didn't found any explicit mentioning
> of this - so wrote up the following myself:
> 
> ======================================================================
> For documentation, we use semantic markup and let the toolchain format
> the text in a consistent and appropriate way. Thus, every occurence of
> a term, like a variable, should use the same markup.  The writing
> should be clear and markup consistent and thus a reader should easily
> know why a certain term is using a specific markup like boldface or
> italics. Explicit use of bold or italics is in general wrong.
> ======================================================================
> 
> Please tell me whether it's accurate and specific enough for this case,
> 
> Andreas
> 

Added now to:
https://wiki.openstack.org/wiki/Documentation/DocBook_conventions#Tags

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF:Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB 21284 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126



More information about the OpenStack-docs mailing list