Open Stack

On Sun, Jul 27, 2014 at 12:58 PM, Anita Kuno <anteaya at anteaya.info> wrote:
> We will have differences of opinion about how and where to use bold and
> other kinds of style choices. I think it is best we get all the opinions
> out in the open so we can then begin to discuss them one at a time and
> craft the guidelines for the infra-manual. While we do this I think we
> still need to review content based patches with an eye that we will
> address formatting once we have agreed to what formatting we want.
>
> Let's keep sharing thoughts so we can continue the discussion.

Thanks everyone for getting this rolling! As an attempt to kick this
off, I left some comments giving my preference (and what felt like
current practices for our team in general) in this review which may be
helpful to the discussion:

https://review.openstack.org/#/c/107303/2/doc/source/developers.rst

See rendered version of the change on docs-draft:
http://docs-draft.openstack.org/03/107303/2/check/gate-infra-manual-docs/b3119a8/doc/build/html/developers.html#work-in-progress

Some examples:

Emphasis using italics rather than bold.

Quotes around patch status adjustments rather than bold (ie "Workflow")

I do understand that use of bold draws attention to certain sections,
but when it's not in sync with typical grammar standards (ie - trying
to use bold for emphasis rather than italics) I find it distracting,
so coming up with some ideas for when it is appropriate to use bold
would be helpful.

-- 
Elizabeth Krumbach Joseph || Lyz || pleia2
http://www.princessleia.com