Open Stack

----- Original Message -----
> From: "Anne Gentle" <annegentle at justwriteclick.com>
> To: "Nermina Miller" <nerminamiller at gmail.com>
> Cc: "Diane Fleming" <diane.fleming at rackspace.com>, "Steve Gordon" <sgordon at redhat.com>,
> openstack-docs at lists.openstack.org
> Sent: Thursday, August 1, 2013 3:47:30 PM
> Subject: Re: [Openstack-docs] Common content strategy?
> 
> On Thu, Aug 1, 2013 at 2:36 PM, Nermina Miller
> <nerminamiller at gmail.com>wrote:
> 
> > +1 for file naming. (Are sections considered separate files?) Have you all
> > thought any further about adding an index? Thanks! - Nermina
> >
> >
> Sections can definitely be separate and it's really nice to have "all one
> page" sections. I'd like them to be written in such a way that we avoid
> that "tiny little paragraph on a page" problem that users have identified.

Sections are also ideal for remixing the content if needed later. The problem if you just dump everything in say a chapter or appendix file (rather than splitting out sections into separate files) is that you are later restricted in terms of where you can include and use that content (chapter has to be immediately under the book element, appendix only at the end, etc.).

> Also, I think that manually indexing is just more work than we want right
> now. To me, there are way too many quality issues to have any resources
> work on an index. Plus, I only like human-made indexes, not machine-made.
> That said, I'm certain that the truly book artifacts will get an index,
> such as when we get a custom edit from O'Reilly on a book. Anyone else have
> a strong opinion?

I share your preference for human-made indexes but the problem of course is doing them well takes a large investment of effort, IMO. Put me down as no strong opinion on that one I guess :).

Thanks,

Steve