Open Stack

On Wed, 2017-08-02 at 09:55 -0500, Matt Riedemann wrote:
> Now that Stephen Finucane is back from enjoying his youth and 
> gallivanting all over Europe, and we talked about a few things in IRC 
> this morning on the docs migration for Nova, I wanted to dump my 
> concerns here for broader consumption.
> 
> 1. We know we have to fix a bunch of broken links by adding in redirects 
> [1] which sdague started here [2]. However, that apparently didn't catch 
> everything, e.g. [3], so I'm concerned we're missing other broken links. 
> Is there a way to find out?

We knew this was going to be an issue, but I wasn't aware of any way to fix
this. The solution looks good though - nice work.

Unfortunately I can't think of any cleverer way to identify these broken links
than manual inspection. I'll do this again for all the patches I've authored
and try to do them for any others I encounter.

> 2. The bottom change in the docs migration series for Nova is a massive 
> refactor of the layout of the Nova devref [4]. That's something I don't 
> want to do in Pike for two reasons:
> 
> a) It's a huge change and we simply don't have the time to invest in 
> properly assessing and reviewing it before Pike RC1.
> 
> b) I think that if we're going to refactor the Nova devref home page to 
> be a certain format, then we should really consider doing the same thing 
> in the other projects, because today they are all different formats 
> [5][6][7]. This is likely a cross-project discussion for the Queens PTG 
> to determine if the home page for the projects should look similar. It 
> seems they should given the uniformity that the Foundation has been 
> working toward lately.

This is fair. I've been working on this with asettle and I personally agree
with a lot of the changes/design decisions made there. However, I understand
the time constraints so we can surely split this out. I'll work with asettle on
this too.

> 3. The patch for the import of the admin guide [8] is missing some CLI 
> specific pages which are pretty useful given they aren't documented 
> anywhere else, like the forced_host part of the compute API [9]. 
> Basically anything that's cli-nova-* in the admin guide should be in the 
> Nova docs. It's also missing the compute-flavors page [10] which is 
> pretty important for using OpenStack at all.

This is a tricky one. Based on previous discussions with dhellmann, the plan
seems to be to replace any references to 'nova xxx' or 'openstack xxx' commands
(i.e. commands using python-novaclient or python-openstackclient) in favour of
'curl'-based requests. The idea here is that the Python clients are not the
only clients available, and we shouldn't be "mandating" their use by
referencing them in the docs. I get this, though I don't fully agree with it
(who really uses curl?). In any case though, this would surely be a big rewrite
and, per your concerns in #2 above,  doesn't sound like something we should be
doing in Pike. I guess a basic import is the way to go for now. I'll take care
of this.

> 4. Similar to #3, but we don't have a patch yet for importing the user 
> guide and there are several docs in the user guide that are Nova 
> specific so I'd like to make sure we include those, like [11][12].

As above.

Stephen

> [1] 
> http://lists.openstack.org/pipermail/openstack-dev/2017-August/120418.html
> [2] https://review.openstack.org/#/c/489650/
> [3] https://review.openstack.org/#/c/489641/
> [4] https://review.openstack.org/#/c/478485/
> [5] https://docs.openstack.org/cinder/latest/
> [6] https://docs.openstack.org/glance/latest/
> [7] https://docs.openstack.org/neutron/latest/
> [8] https://review.openstack.org/#/c/477497/
> [9] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/cli-nova-specify-host.rst
> [10] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-gu
> ide/source/compute-flavors.rst
> [11] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-launch-instances.rst
> [12] 
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-gui
> de/source/cli-delete-an-instance.rst
>