On Mon, 22 May 2017 09:39:09 +0000
Alexandra Settle <a.set...@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:


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.


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe

Reply via email to