Open Stack

After a busy week last week, we made some good progress with the
documentation migration project. We still have quite a few repositories
that haven't been started, though, so please keep working. If you
need assistance preparing or reviewing the patches, let us know
with a follow-up email to this thread or by asking in #openstack-docs.

Because we still have a lot of work to do in the openstack-manuals
repo, the documentation team has started landing patches to remove
the content that is being migrated into project repositories. If
you have not yet started your migration, check out the commit tagged
"before-migration" in openstack-manuals to find the content to be
migrated.

As part of this work today we have also prepared a patch to move
all remaining projects to the new documentation build jobs. This
will cause any content from doc/source to be published to
docs.o.o/$project/latest instead of docs.o.o/developer/$project.
Project teams still need to reorganize this content as described
in the spec to ensure the automatically generated landing pages
point to the correct URLs.

We need to complete this migration work before creating stable
branches, to avoid having to backport the documentation changes.

Over the course of last week, we had a few questions about the
directions and about reviews.

1. Please use the gerrit topic "doc-migration" for all of the patches
related to this work. We are monitoring the available changes by
using that topic in queries, and we won't see your patches to help
with reviews if you use another topic. Tying your patch to the
blueprint using "Blueprint: doc-migration" will set the topic of
the patch to "bp/doc-migration", and the patches will not appear
in the query results.

2. Please work on the steps in the order given. We have had quite
a few patches that only apply the new theme, without reorganizing
the content for the projects. These projects will not be linked
properly from the templated landing pages, so your users will have
trouble finding your documentation.

3. Only official OpenStack projects, under TC governance, should
use the openstackdocs theme. Projects publishing their documentation
to readthedocs.org or other sites should not use the theme, and do
not need to take any of the other migration steps.

4. Reviewers, please prioritize landing the intiial content import
and ask for follow-up patches to fix issues, unless the content is
just absolutely wrong. Whitespace issues, typos, etc. should all
be fixed after the initial import of the content created by the
documentation team is complete.

5. Projects with a "deployment guide" instead of "install guide"
need to make sure they are using the openstackdocs theme and to
update the organization of the rest of their content. The deployment
guide should stay where it is, for now.

6. We've had a couple of cases where multiple people did the same
work because neither put their name next to the repository in the
list on https://etherpad.openstack.org/p/doc-migration-tracking.
We have plenty of this work to go around! Please use the etherpad
to sign up for the repo you are going to work on *before* starting
to write patches, so that we can avoid duplicating effort!

If you run into trouble or have other questions, please follow-up
here or ping us in the #openstack-doc IRC channel on Freenode.

Doug