Open Stack

On Mon, 22 May 2017 09:39:09 +0000
Alexandra Settle <a.settle at outlook.com> wrote:

(...)

> Until this point, the documentation team has owned several manuals that include
> content related to multiple projects, including an installation guide, admin
> guide, configuration guide, networking guide, and security guide. Because the
> team no longer has the resources to own that content, we want to invert the
> relationship between the doc team and project teams, so that we become liaisons
> to help with maintenance instead of asking for project teams to provide liaisons
> to help with content. As a part of that change, we plan to move the existing
> content out of the central manuals repository, into repositories owned by the
> appropriate project teams. Project teams will then own the content and the
> documentation team will assist by managing the build tools, helping with writing
> guidelines and style, but not writing the bulk of the text.

First off, thanks a lot for sending this out!

If my understanding is correct, the openstack-manual repo would only store
static index pages and some configuration files? Everything under
https://github.com/openstack/openstack-manuals/tree/master/doc would be
moved to project repos? 

The installation guide is special in that project-specific in-tree guides
still depend on common content that currently lives in openstack-manuals.
Where would that common content go, then?

This includes installation guide sections such as:

https://docs.openstack.org/ocata/install-guide-rdo/overview.html
https://docs.openstack.org/ocata/install-guide-rdo/environment.html
https://docs.openstack.org/ocata/install-guide-rdo/launch-instance.html

Also, unlike the openstack-manual's installation guide content, the in-tree
guides do not use conditional content for different distributions. I assume
individual projects would need to maintain separate common content for
each distribution?

(...)

> 3. We could do option 2, but use a separate repository for the new user-oriented
> documentation. This would allow project teams to delegate management of the
> documentation to a separate review project-sub-team, but would complicate the
> process of landing code and documentation updates together so that the docs are
> always up to date.

If the intention here is to make the content more visible to developers who
work in project repos, then separating the content to a different repo
kind of goes against that idea, I think.

Cheers,
pk