[openstack-dev] [nova][docs] Concerns with docs migration

Matt Riedemann mriedemos at gmail.com
Wed Aug 2 14:55:02 UTC 2017

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?

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.

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.

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

[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/




More information about the OpenStack-dev mailing list