Open Stack

On Thu, Sep 1, 2016 at 4:30 PM, Steve Martinelli <s.martinelli at gmail.com>
wrote:

> cc'ed dtroyer (osc ptl)
>
> Duplication is a part of Akihiro's initial comment, and I think the the
> OSC shouldn't maintain it's own copy of this, but rather redirect to the
> docs page. I'd be more than happy to get rid of the OSC docs, before doing
> that I did a quick comparison between http://docs.openstack.org/cli-
> reference/openstack.html and http://docs.openstack.org/developer/python-
> openstackclient/command-list.html
>

I don't agree with removing the docs from the OSC repo, we try to require
docs updates in the same review as code changes, that will be impossible
otherwise and the published docs will always lag.  How will the docs.o.o
version be maintained current?

If there is something we can do to facilitate a periodic update of
docs.o.o, I am all for it, be it on every commit or at release time (we
release as-needed, not on the integrated cycle), which is my preference.

Also note that our current RST docs contain more than just a one-for-one of
the help output.  It should contain MUCH more in the way of explanation.

On 02/09/16 03:19, Akihiro Motoki wrote:
>> > OSC also recently introduced "beta" command concept [1].
>> > Another point is how the cli-ref provided by openstack-manuals treats
>> it.
>> > [1] http://docs.openstack.org/developer/python-openstackclient/
>> command-beta.html
>>
>
Please do not document beta commands in end-user-visible places.  These
commands are specifically made with the enable switch so they do not get
picked up before they are ready for general use.

dt

-- 

Dean Troyer
dtroyer at gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160901/1e61233a/attachment.html>