Open Stack

Hi all,

I'll say it's not as bad as I originally thought. I wrote up the spec here:

https://review.openstack.org/345639

These guides are affected:
admin-guide
cli-reference (glance_property_keys.rst is the only file)
ops-guide
user-guide

source/common/

I have a couple of questions on the review:

Do we want this set of changes for newton? Only the cli-reference is
"versioned" currently.
How are the <guide-name>/source/common/ files sourced? (Hoping those
are a change once get many proposition.)

Thanks,
Anne


On Tue, Jul 19, 2016 at 8:10 AM, Olena Logvinova
<ologvinova at mirantis.com> wrote:
> Then it makes sense. Thanks for clarification, Anne! I can also help with
> the changes.
>
> Best
> Olena
>
> On Tue, Jul 19, 2016 at 4:05 PM, Anne Gentle <annegentle at justwriteclick.com>
> wrote:
>>
>> Sorry, I have to over rule. The hyphen convention is for search
>> optimization and find ability. [2]
>>
>> I hear your consistency desire to match Python, but our outcome and
>> overall goals are to write docs that are readable and findable. Let's say
>> each document file is a package-like entity rather than a module. :)
>>
>> Thanks,
>> Anne
>>
>> 2. https://support.google.com/webmasters/answer/76329?hl=en
>>
>>
>> On Jul 19, 2016, at 12:59 AM, Olena Logvinova <ologvinova at mirantis.com>
>> wrote:
>>
>> +1 for changing the convention to underscore instead of hyphen.
>>
>> As far as I am concerned, visually it's easier to read and distinguish
>> words in a filename with underscore, bc underscore has a bigger length than
>> hyphen.
>>
>> Thanks
>> Olena
>>
>>
>> 19 июля 2016 г. 8:43 AM пользователь "Akihiro Motoki" <amotoki at gmail.com>
>> написал:
>>>
>>> I don't know the background of the current convention.
>>> Is there any reason we prefer to hyphens over underscores?
>>>
>>> In Python we need to use underscores for such cases.
>>> I think most developers familiar with python tend to use underscore as
>>> delimiters.
>>> IMHO it is better to use same convention on file naming in python and
>>> docs.
>>>
>>> I hit some differences between openstack-manuals and python (or project
>>> devref),
>>> for example, RST title conventions, file naming.
>>>
>>> Akihiro
>>>
>>> 2016-07-19 5:30 GMT+09:00 Anne Gentle <annegentle at justwriteclick.com>:
>>> > I kept trying to put this off, but... I think I'll dive right in.
>>> >
>>> > I see we have style guidance to use hyphens for file names [1], but in
>>> > the repo, there are still RST files with underscores in the names. I'm
>>> > sure it's due to the original xml:id having underscores.
>>> >
>>> > I can take on the task of renaming, and I'd like to write a spec to
>>> > make sure I don't miss anything: Cross reference links? Redirects?
>>> > Tackle the work a guide at a time? Finding other contributors who hate
>>> > inconsistency? Timing with the release? Making sure we really want
>>> > this? :)
>>> >
>>> > Does a spec sound good? Or can you convince me this change isn't worth
>>> > the effort?
>>> >
>>> > Thanks,
>>> > Anne
>>> >
>>> > 1.
>>> > http://docs.openstack.org/contributor-guide/docs-structure.html#file-naming-conventions
>>> > --
>>> > Anne Gentle
>>> > www.justwriteclick.com
>>> >
>>> > _______________________________________________
>>> > 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
>
>
>
>
> --
> Best regards,
> Olena Logvinova,
> Technical Writer | Mirantis, Kharkiv | 38, Lenin av., Kharkiv
> ologvinova at mirantis.com | +380950903196



-- 
Anne Gentle
www.justwriteclick.com