Open Stack

Oops... didn't reply-all the first time.

IDs came up as a consistency issue from the installation guide audit. Since
any changes would impact references and patches for other issues, I wanted
to discuss the situation early in the process of improving the installation
guide. Whatever we decide for filenames and IDs, it should go into our
conventions page for future reference.


On Mon, May 26, 2014 at 8:47 AM, Diane Fleming
<diane.fleming at rackspace.com>wrote:

>   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>
> Date: Monday, May 26, 2014 9:42 AM
> To: Diane Fleming <diane.fleming at rackspace.com>
> Cc: Anne Gentle <anne at openstack.org>, Andreas Jaeger <aj at suse.com>, "
> openstack-docs at lists.openstack.org" <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> 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> wrote:
>>
>>
>>
>>
>> On Sun, May 25, 2014 at 4:50 PM, Steve Gordon <sgordon at redhat.com> wrote:
>>
>>> ----- Original Message -----
>>> > From: "Anne Gentle" <anne at openstack.org>
>>> > To: "Andreas Jaeger" <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
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>
>>
>> _______________________________________________
>> 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/20140526/545c147a/attachment.html>