Open Stack

On Wed, Mar 12, 2014 at 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.
>
>

I would like our printed book, the Operations Guide, to have a conventions.

I would like author conventions to remain on the wiki.

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

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

Anne


>
>
>>  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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20140312/c7bed08d/attachment.html>