Open Stack

On Mon, May 22, 2017 at 09:39:09AM +0000, Alexandra Settle wrote:

[snip]

> 1. We could combine all of the documentation builds, so that each project has a single doc/source directory that includes developer, contributor, and user documentation. This option would reduce the number of build jobs we have to run, and cut down on the number of separate sphinx configurations in each repository. It would completely change the way we publish the results, though, and we would need to set up redirects from all of the existing locations to the new locations and move all of the existing documentation under the new structure.
> 
> 2. We could retain the existing trees for developer and API docs, and add a new one for "user" documentation. The installation guide, configuration guide, and admin guide would move here for all projects. Neutron's user documentation would include the current networking guide as well. This option would add 1 new build to each repository, but would allow us to easily roll out the change with less disruption in the way the site is organized and published, so there would be less work in the short term.
> 
> 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.
> 

I actually like the first two a little better, but I think this might actually be the best option. My hope
would be that there could continue to be a docs team that can help out with some of this, and by having a
separate repo it would allow usto set up separate teams with rights to merge.

> Personally, I think option 2 or 3 are more realistic, for now. It does mean that an extra build would have to be maintained, but it retains that key differentiator between what is user and developer documentation and involves fewer changes to existing published contents and build jobs. I definitely think option 1 is feasible, and would be happy to make it work if the community prefers this. We could also view option 1 as the longer-term goal, and option 2 as an incremental step toward it (option 3 would make option 1 more complicated to achieve).
> 
> What does everyone think of the proposed options? Questions? Other thoughts?
> 
> Cheers,
> 
> Alex
> 
> 

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