Open Stack

On 07/22/2014 04:39 PM, Pavel Sedlak wrote:
> 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.

That's why I said, I would be fine splitting it up in two pages - one
page that handles content we both can use, one that is specific for DocBook.

> 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

Coming from a different background, I would say use "code" for these and
"code" gets then rendered in a special font...

>   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".

That's something I would not use.

But I see we're discussing different levels here. Style for me is much
more than marking content, it includes whom to address ("you can do..."
vs "we do" ...), spelling, usage of words,...

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

It is - but that's why it's important to have one guideline. In the
documentation team we discuss those and listen to the professional
editors that are part of our team,


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

The sentences itself need to read fine as well ;)

Andreas

> 
> .. _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
>>
> 


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