Open Stack

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.

> 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 page is for writers - the section we are discussing is
for *readers*.

Yes, we could create a separate wiki page but our readers will not find
it. We provide PDFs that people can print out and read off-line. It
should IMO all be in one place?

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