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

Akihiro Motoki amotoki at gmail.com
Wed Aug 2 15:55:35 UTC 2017


Thanks for summarizing the concerns. It is really helpful for all projects!

2017-08-02 23:55 GMT+09:00 Matt Riedemann <mriedemos at gmail.com>:
> 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.

Totally agree for PTG topics. we need some guideline on what the top pages of
individual projects should be and what are expected for top pages of
sub directories.
When the doc-migration started, I chatted on this a bit with asettle.
The top page of each subdirectory (like admin, install and so on) are
expected to link
from a landing page on docs.openstack.org. On the other hand, we also need to
take care of the top page of individual projects. In neutron case, we
basically try to
accommodate all documents in the standard directory structure and keep
the top page as much as simple.
It is really nice to have a consistent guideline on this.

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

Perhaps what we need are pages which explains how to use and configure
a specific feature using on CLI and/or some. It might be beyond the
scope of cli-nova-*.
I think the end-user and admin guides can be refactored per topic.

> 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].
>
> [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-guide/source/cli-nova-specify-host.rst
> [10]
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/admin-guide/source/compute-flavors.rst
> [11]
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-launch-instances.rst
> [12]
> https://github.com/openstack/openstack-manuals/blob/stable/ocata/doc/user-guide/source/cli-delete-an-instance.rst
>
> --
>
> Thanks,
>
> Matt
>
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



More information about the OpenStack-dev mailing list