Open Stack

On 07/22/2014 11:08 AM, Andreas Jaeger wrote:
> 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
>>>
>>
> 
> 
Thank you, we are off to a good start.

I would like to take some time to digest the conventions offered by the
docs team before I comment.

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.

This is great, thank you,
Anita.