Open Stack

+2 from me... thanks everyone!


On Wed, May 28, 2014 at 8:20 AM, Anne Gentle <anne at openstack.org> wrote:

>
>
>
> 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
>>>
>>>
>>
>
> _______________________________________________
> 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/ac336025/attachment-0001.html>