<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Mar 12, 2014 at 4:46 PM, Lana Brindley <span dir="ltr"><<a href="mailto:openstack@lanabrindley.com" target="_blank">openstack@lanabrindley.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="">On 12/03/14 17:24, Andreas Jaeger wrote:<br>


<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
On 03/12/2014 07:25 AM, Lana Brindley wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
On 11/03/14 04:40, Andreas Jaeger wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
On 03/10/2014 05:42 PM, Gauvain Pocentek wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Thank you all for the feedback!<br>
<br>
I've updated the wiki and will get started on the 'conventions used in<br>
this book' part.<br>
</blockquote>
<br>
Thanks a lot!<br>
<br>
Make it a common chapter/section that we include everywhere - perhaps<br>
together with the revision history?<br>
<br>
<br>
Andreas<br>
<br>
</blockquote>
<br>
I'm really not convinced that adding a bunch of front-matter is an<br>
appropriate solution here. I'm a big believer in standards, yes, but I<br>
also don't think those standards need to be advertised in bold writing<br>
in the front of every book. It should be enough that we have them, are<br>
aware of them, and abide by them as much as possible.<br>
</blockquote>
<br>
Would you feel better if those were an appendix?<br>
<br>
Looking at printed books, I'm used to these conventions at the start of<br>
the book that explain the reader some of these - and that's the example<br>
I have in mind to follow.<br>
</blockquote>
<br></div>
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.<div class="">

<br></div></blockquote><div><br></div><div><br></div><div>I would like our printed book, the Operations Guide, to have a conventions. </div><div><br></div><div>I would like author conventions to remain on the wiki.</div>
<div>
<br></div><div>I would like a VERY BRIEF common reader Conventions section at the start of each book. Gauvain's draft is what I was thinking of. </div><div><br></div><div><a href="https://review.openstack.org/#/c/79445/3/doc/common/section_conventions.xml">https://review.openstack.org/#/c/79445/3/doc/common/section_conventions.xml</a><br>

</div><div><br></div><div>I also dislike super heavy more-than-a-page conventions sections that clutter up books. That's not this. This should just give a heads-up to readers. The only additional definition we might want is what's a tip, what's a note, what's a warning. Writers need much more guidance and that should remain on the wiki. :)</div>

<div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="">
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
Is there a good argument why they need to be in the front matter, rather<br>
than existing on our wiki<br>
(<a href="https://wiki.openstack.org/wiki/Documentation/Conventions" target="_blank">https://wiki.openstack.org/<u></u>wiki/Documentation/Conventions</a><u></u>)? After all,<br>
the wiki is open to the public. Perhaps a single link to this page in<br>
the preface would suffice instead?<br>
</blockquote>
<br>
The Conventions page is for writers - the section we are discussing is<br>
for *readers*.<br>
</blockquote>
<br></div>
What benefit does it bring to our readers to have this information?<div class=""><br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Yes, we could create a separate wiki page but our readers will not find<br>
it. We provide PDFs that people can print out and read off-line. It<br>
should IMO all be in one place?<br>
</blockquote>
<br></div>
Have you ever met someone who confessed to printing them out?<div class="im"><br>
<br>
L<br>
<br>
-- <br>
Lana Brindley<br>
Technical Writer<br>
Rackspace Cloud Builders Australia<br>
<a href="http://lanabrindley.com" target="_blank">http://lanabrindley.com</a><br>
<br></div><div class=""><div class="h5">
______________________________<u></u>_________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org" target="_blank">Openstack-docs@lists.<u></u>openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-docs</a><br>
</div></div></blockquote></div><br></div></div>