Open Stack

Le 2014-03-13 07:42, Andreas Jaeger a écrit :
> On 03/13/2014 04:26 AM, Lana Brindley wrote:
>> On 13/03/14 10:11, Anne Gentle wrote:
>>> 
>>> 
>>> 
>>> On Wed, Mar 12, 2014 at 4:46 PM, Lana Brindley
>>> <openstack at lanabrindley.com <mailto:openstack at lanabrindley.com>> 
>>> wrote:
>>> 
>>>     On 12/03/14 17:24, Andreas Jaeger wrote:
>>> 
>>>         On 03/12/2014 07:25 AM, Lana Brindley wrote:
>>> 
>>>             On 11/03/14 04:40, Andreas Jaeger wrote:
>>> 
>>>                 On 03/10/2014 05:42 PM, Gauvain Pocentek wrote:
>>> 
>>>                     Thank you all for the feedback!
>>> 
>>>                     I've updated the wiki and will get started on 
>>> the
>>>                     'conventions used in
>>>                     this book' part.
>>> 
>>> 
>>>                 Thanks a lot!
>>> 
>>>                 Make it a common chapter/section that we include
>>>                 everywhere - perhaps
>>>                 together with the revision history?
>>> 
>>> 
>>>                 Andreas
>>> 
>>> 
>>>             I'm really not convinced that adding a bunch of 
>>> front-matter
>>>             is an
>>>             appropriate solution here. I'm a big believer in 
>>> standards,
>>>             yes, but I
>>>             also don't think those standards need to be advertised 
>>> in
>>>             bold writing
>>>             in the front of every book. It should be enough that we 
>>> have
>>>             them, are
>>>             aware of them, and abide by them as much as possible.
>>> 
>>> 
>>>         Would you feel better if those were an appendix?
>>> 
>>>         Looking at printed books, I'm used to these conventions at 
>>> the
>>>         start of
>>>         the book that explain the reader some of these - and that's 
>>> the
>>>         example
>>>         I have in mind to follow.
>>> 
>>> 
>>>     I don't see any reason why we should be following the herd on 
>>> this.
>>>     "Because printed books do it" isn't ever a good reason for us 
>>> to,
>>>     the delivery mechanism is completely different, as are the 
>>> reasons
>>>     why people are using our docs, and the attitudes and assumptions
>>>     they bring with them.
>>> 
>>> 
>>> 
>>> I would like our printed book, the Operations Guide, to have a
>>> conventions.
>> 
>> Agreed.
>> 
>>> 
>>> I would like author conventions to remain on the wiki.
>> 
>> Agreed.
>> 
>>> 
>>> I would like a VERY BRIEF common reader Conventions section at the 
>>> start
>>> of each book. Gauvain's draft is what I was thinking of.
>>> 
>>> https://review.openstack.org/#/c/79445/3/doc/common/section_conventions.xml
>>> 
>> 
>> It needs to be fleshed out a little, as it seems a bit odd with only 
>> the
>> command prompt conventions listed. I would want to be very careful 
>> that
>> it doesn't get too lengthy.
> 
> Do you want to give it a shot to make it less "odd"?

Lana, feel free to hijack my patch if you feel inspired :)

Thanks,
Gauvain