Open Stack

+1 subdirectories
Diane
----------------------------------------------
Diane Fleming
Software Developer II - US
diane.fleming at rackspace.com
Cell  512.323.6799
Office 512.874.1260
Skype drfleming0227
Google-plus diane.fleming at gmail.com

From: Matt Kassawara <mkassawara at gmail.com<mailto:mkassawara at gmail.com>>
Date: Monday, May 26, 2014 10:53 AM
To: Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>>
Cc: Andreas Jaeger <aj at suse.com<mailto:aj at suse.com>>, "openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>" <openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>>
Subject: Re: [Openstack-docs] Conventions for filenames and chapter/section IDs

I like the idea of subdirectories. During the installation guide updates project, I broke the neutron content into smaller files to simplify editing and to reduce chances of patch collisions. However, this increased the overall number of files. Implementing subdirectories would mitigate this issue. The installation guide swift chapter already uses a subdirectory which I'm debating suggesting for the remainder of the installation guide and potentially other books.


On Mon, May 26, 2014 at 9:32 AM, Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> wrote:
OK, so as I'm breaking out the HA chapter at this very minute, let me throw something else into the mix.  The HA Guide is broken into 2 parts, each with a number of chapters, each with a number of sections.  Right now I've broken it down into chapter files, but as I get down to the section level I begin to get overwhelmed with the number of files.  Is there any objection to grouping section files in folders by chapter?  For example:

ch_aa_network.xml
ch_aa_network/sec_run_neutron_dhcp_agent.xml

I mean, I can just as easily make it

ch_aa_network.xml
sec_run_neutron_dhcp_agent.xml

But it starts to get really messy.

Thoughts?

----  Nick



On Sun, May 25, 2014 at 5:50 PM, Steve Gordon <sgordon at redhat.com<mailto:sgordon at redhat.com>> wrote:
----- Original Message -----
> From: "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>>
> To: "Andreas Jaeger" <aj at suse.com<mailto:aj at suse.com>>
>
> Something to think about for ch and sec is that we won't always author in a
> book-like manner, so let's not lock ourselves into that sort of thinking
> due to current file names.
>
> Stick to the install guide for now, to apply conventions, just please don't
> use something as meaningful semantically as chapter and section.

I actually think it's important/useful information in the filename. It reflects the root node of the file's XML which has an impact on where you can nest/include it in another document (you can't include a chapter in a section for example, but you can include a section in a chapter). It's got more to do with the realities of the format being used than whether we're thinking in terms of books, articles, etc.

Granted if we moved to a non-XML format this would no longer be the case, but I think we'd have bigger conversion issues than bulk renaming the files/links. ;)

-Steve

_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org<mailto: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/20140526/86fc4365/attachment-0001.html>