Open Stack

I tend to agree that we don't need spelled-out conventions - unless
there's something that might be confusing to the reader.

(And I used to have an office-mate at IBM years ago who would print out
the massive MVS message manuals and pile them on top of his terminal. Then
he would take a nap at his desk for most of the afternoon. I guess he
thought that if he had stacks of paper everywhere it would look like he
was working?! Ha ha. )



Diane
----------------------------------------------
Diane Fleming
Software Developer II - US

diane.fleming at rackspace.com
Cell  512.323.6799
Office 512.874.1260
Skype drfleming0227
Google-plus diane.fleming at gmail.com






On 3/12/14 4:46 PM, "Lana Brindley" <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.
>
>>
>>> 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
>
>_______________________________________________
>Openstack-docs mailing list
>Openstack-docs at lists.openstack.org
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs