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ó __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
