Open Stack

On 13/03/14 10:11, Anne Gentle wrote:
>
>
>
> On Wed, Mar 12, 2014 at 4:46 PM, Lana Brindley
> <openstack at lanabrindley.com <mailto: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.
>
>
>
> I would like our printed book, the Operations Guide, to have a conventions.

Agreed.

>
> I would like author conventions to remain on the wiki.

Agreed.

>
> 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.
>
> https://review.openstack.org/#/c/79445/3/doc/common/section_conventions.xml

It needs to be fleshed out a little, as it seems a bit odd with only the 
command prompt conventions listed. I would want to be very careful that 
it doesn't get too lengthy.

>
> 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. :)

Yes, I think that the admonition guidance is good, in addition to the 
prompts. Perhaps we can draw a line there?

To give you a little more background, I'm once bitten twice shy on this 
matter. Pages and pages of heavy convention material to wade through at 
the beginning of an online book is tedious for readers (and writers!). 
It becomes so much part of the furniture that it's rarely checked or 
updated. And there's nothing worse than a book that doesn't conform to 
its own stated standards. Sometimes it's better to not state them than 
to flagrantly flaunt them.

L


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