Open Stack

Hi Alex,

First of all thank you for writing this up the summary and list options with their expected impacts.

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

I’m fully in favor for option #1 and/or option #2. From the perspective of trying to move step-by-step and give a chance to project teams to acclimatize with the changes I think starting with #2 should be sufficient.

Although if we think that option #1 is doable as a starting point and also end goal, you have my support for that too.

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

As being one of the advocates on having the documentation living together with the code so we can give a chance to the experts of the code changes to add the corresponding documentation as well, I'm definitely against option #3. :)

Thanks and Best Regards,
Ildikó