Open Stack

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.

>
>> 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*.

What benefit does it bring to our readers to have this information?


>
> 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?

Have you ever met someone who confessed to printing them out?

L

-- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com