[OpenStack-Infra] Style Guide for Infra Manual

Pavel Sedlak psedlak at redhat.com
Tue Jul 22 14:39:02 UTC 2014


Hi.

While the `general conventions`_ seems to cover lot of things,
I'm not really convinced it can do work well for our case.

First part, writing style, probably could (and should?) be followed here.

But rest is not directly applicable, as we are not using DocBook but rst.

Though of course when there are matching options (like ".. Note::" for
marking side notes) I'm for using them as much as possible/feasible
(to later simplify for example styling per mass).

What I've used in my proposal is not just meta-information markers
(code citation, command, program name, ...) but also emphasize most
important part of the paragraph/section (in the sense of the information
we are trying to transfer to user/reader).

For example, see how the final output of my `proposal patch`_ looks
like, when `rendered as html`_.


I didn't had much time to write down my style-guide proposal yet,
but at least I can draft my idea (what i +- followed in the patches):

- exact name/quotation of some element in italics
  as it differentiates it from surrounding text,
  but does not steals focus of the reader (too much)

  > look for *Review* button, click *Submit*

- core point(s) of transferred idea in bold font
  as that should make strong memory-bound to the described topic,
  as also allow quick scanning through the text
  (try it on those two sections of the proposal change `rendered as html`_
   read just the section headline a only(!) the text in bold font)
  For this there could be suggested general limit, as "please try to
  use ~2 highlights per paragraph at most".

  e.g. in section about contributing to infra-manuals:
  > when doing changes you should **follow style guide** and
  > submit all your modifications to **gerrit** for **review**


I totally agree that this can be subjective and/or sensitive topic.

But on contrary having long documents structured just by headlines/code blocks
to something like uniform grey paper boxes, does not make me feel
like it was written by/for humans. Of course having text in chaotic 'grid'
with rainbow-like look is probably worse.

.. _general conventions: https://wiki.openstack.org/wiki/Documentation/Conventions
.. _proposal patch: https://review.openstack.org/#/c/107360
.. _rendered as html: http://docs-draft.openstack.org/60/107360/3/check/gate-infra-manual-docs/db428f9/doc/build/html/developers.html#code-review

----- Original Message -----
> From: "Andreas Jaeger" <aj at suse.com>
> To: "Anita Kuno" <anteaya at anteaya.info>, openstack-infra at lists.openstack.org, "Anne Gentle" <anne at openstack.org>
> Sent: Tuesday, July 22, 2014 8:29:13 AM
> Subject: Re: [OpenStack-Infra] Style Guide for Infra Manual
> 
> On 07/21/2014 10:30 PM, Anita Kuno wrote:
> > Currently infra-manual doesn't have a style guide. We need one.
> > 
> > There was some great work done at the QA/Infra meetup on infra-manual.
> > Pavel was offering some style markup for the infra-manual, but since we
> > don't have a style guide yet, it is difficult to get consistency with
> > the markup.
> > 
> > Let's collect our thoughts about how we would like style to be used in
> > the infra-manual. We can then create a style-guide file inside the repo
> > to direct future patches and reviews.
> > 
> > Who has some thoughts on this?
> 
> I suggest to follow the conventions that the Doc team is using:
> 
> https://wiki.openstack.org/wiki/Documentation/Conventions
> 
> If it helps, we can easily split this up so that we can both use it,
> 
> Andreas
> --
>  Andreas Jaeger aj@{suse.com,opensuse.org} Twitter: jaegerandi
>   SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
>    GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
>     GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126
> 
> _______________________________________________
> OpenStack-Infra mailing list
> OpenStack-Infra at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
> 

-- 
Pavel Sedlák <psedlak at redhat.com>
 OpenStack Quality Engineer
 Red Hat Czech / BRQ
 irc: psedlak




More information about the OpenStack-Infra mailing list