Open Stack

That looks good.

My only change would be that sections should be section_*, only because that's how most of them are named at the moment so it would save a lot of work to keep what we already have.

I have also used created other files for content sharing, such as itemized lists or tables. I usually prefix the file name with the object type in the file.

itemizedlist_service_list.xml (for example)
table_server_status.xml

Oh, and for prefaces, I just use

preface.xml


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: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
Date: Wednesday, May 28, 2014 9:04 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

Here's what I'll update in the Documentation/Conventions page if everyone agrees:

For file names, use bk_ ch_ and sec_ at the beginning of the file name to indicate the type of file it is in the hierarchy of the build. For further organization, you can use subdirectories to organize the files by a particular grouping such as project or topic.

For xml:id creation, follow these guidelines.
 - xml:id must be unique across a built deliverable, otherwise you get build errors
 - xml:id creates the HTML file name so it should be human-readable, not codified like the file name
 - xml:id should closely follow the actual title in the text, using dashes for spaces
 - xml:id creation should consider search and find-ability as well as human-readability

I prefer not to document the use a processing instruction like <?dbhtml filename="name"> as that should be the rare exception.

Thanks,
Anne


On Mon, May 26, 2014 at 11:13 AM, Nick Chase <nchase at mirantis.com<mailto:nchase at mirantis.com>> wrote:
My concern on this is that it raises a barrier to entry for contributors.  It's not intuitive.  As a fix in an emergency, sure.  But I'd be concerned about building this out as the standard way we do things.

----  Nick


On Mon, May 26, 2014 at 11:43 AM, David Cramer <david.cramer at rackspace.com<mailto:david.cramer at rackspace.com>> wrote:
On 5/26/14, 10:07 AM, Nick Chase wrote:
> Plus my concern in changing Id values is breaking any references.

You can reduce (but not eliminate) the impact of a file name change by
changing the file names via a processing instruction:

<section xml:id="some-dumb-id"><?dbhtml filename="intro.html"?>...

If you use <?dbhtml filename="..."?> you'll get the aesthetically
pleasing intro.html file name without having to change the xml:id and
break xrefs to the section. However, if you have external links to
some-dumb-id.html from other documents, those links would obviously break.

Regardless of the publishing tool chain, when changing the names of
existing resources on the web, the best approach is to add 301 redirects
to avoid breaking bookmarks, links, and losing SEO karma.

Regards,
David



_______________________________________________
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/20140528/101b742b/attachment-0001.html>