Open Stack

Hey Lana,

Le 2014-03-12 07:25, Lana Brindley a écrit :
> 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.

I get your point. I've seen one or two users asking questions about the 
prompts, that's why I suggested to add a description of what we use in 
the guide. I confess that having seen lots of "conventions used in this 
book" chapters I've been inclined to do the same for our doc. This might 
not be relevant for us. I trust the judgement of professional writers on 
this :)

> 
> Is there a good argument why they need to be in the front matter,
> rather than existing on our wiki
> (https://wiki.openstack.org/wiki/Documentation/Conventions)? After
> all, the wiki is open to the public. Perhaps a single link to this
> page in the preface would suffice instead?

The conventions wiki page is probably too detailed for readers, they 
don't care how we manage docbook tags. They probably don't care about 
docbook at all for that matter.

What about a new ConventionsForReaders wiki page linked from the books?

Thanks,
Gauvain