Open Stack

Matt,

What problem are you trying to solve by updating the xml:id values?

I'd start with one issue – the file names – and then figure out what you want to accomplish by changing xml:id values.

I personally don't see much value-add with updates to the ID's, but I could be missing something!

thanks,

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 9:42 AM
To: Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>>
Cc: Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>, 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

How about describing the hierarchy in IDs, but not necessarily with ch_, section_, etc? For example:

ch_networking -> networking
section_neutron-networking-ml2 -> networking-neutron-ml2
section_neutron-ml2-controller-node -> networking-neutron-ml2-controller-node

Also, would it help to indicate type in figure, table, and similar element IDs? For example:

example-architecture-with-legacy-networking -> fig_example-architecture-with-legacy-networking
table1 -> tab_getstart-openstack-services (from common/ch_getstart.xml)
para3 -> par_getstart-3 (from common/ch_getstart.xml)

Or... am I still the totally crazy noob?

P.S. - I'm also interested in ideas for standardizing filenames and/or locations for figures.


On Sun, May 25, 2014 at 5:59 PM, Diane Fleming <diane.fleming at rackspace.com<mailto:diane.fleming at rackspace.com>> wrote:
+1 for file name conventions
-1 for xml:id conventions



Sent from my iPhone

On May 25, 2014, at 6:28 PM, "Anne Gentle" <anne at openstack.org<mailto:anne at openstack.org>> wrote:




On Sun, May 25, 2014 at 4: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.

I agree it's a useful codification in the file name, but I don't think we want it in the xml:id. The xml:id is used for SEO, for human-readable URLs, and so on. Let's not leak our abstraction further than we have to. :)
Anne


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/35a8d507/attachment.html>