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-requ...@lists.openstack.org?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __________________________________________________________________________ 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
