Open Stack

I agree with Andrea. We need a conventions page for readers. I find it 
very helpful
when I am reading a manual and have a question regarding basic 
conventions being
used to have one location that contains conventions information to use 
for reference.

Phil

On 03/12/2014 02:24 AM, 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.
>
>> 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