Open Stack

On 03/13/2014 04:26 AM, Lana Brindley wrote:
> 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.

Do you want to give it a shot to make it less "odd"?

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

Right now, I agree we should draw the line here. And I hope that we
don't have to extend it in the future.

I would have only added the command prompt conventions, we received
already some bug reports for the Install Guide where we had to explain
this. So, this needs to be documented.


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

Yeah, indeed.

Currently I see us getting better in following our conventions - and not
setting the bar too high,

Andreas
-- 
 Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
  SUSE LINUX Products GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
   GF: Jeff Hawn,Jennifer Guild,Felix Imendörffer,HRB16746 (AG Nürnberg)
    GPG fingerprint = 93A3 365E CE47 B889 DF7F  FED1 389A 563C C272 A126