Open Stack

Le 2014-03-13 04:26, Lana Brindley a écrit :
> 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.
> 
>> 
>> I also dislike super heavy more-than-a-page conventions sections that
>> clutter up books. That's not this. This should just give a heads-up 
>> to
>> readers. The only additional definition we might want is what's a 
>> tip,
>> what's a note, what's a warning. Writers need much more guidance and
>> that should remain on the wiki. :)
> 
> Yes, I think that the admonition guidance is good, in addition to the
> prompts. Perhaps we can draw a line there?

I agree, let's not add too much.

Gauvain