Open Stack

On Wed, May 28, 2014 at 9:10 AM, Diane Fleming
<diane.fleming at rackspace.com>wrote:

>   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.
>

Ha, oops, I should have known that, sorry.


>
>  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
>
>
Makes sense. The table_prefix is very helpful.


>  Oh, and for prefaces, I just use
>
>  preface.xml
>
>
Ok, I'll note in the wiki page. 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: Anne Gentle <anne at openstack.org>
> Date: Wednesday, May 28, 2014 9:04 AM
>
> To: Nick Chase <nchase at mirantis.com>
> Cc: 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
>
>   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> 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> 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
>> 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/b76bd876/attachment.html>