I'm in favor of option #1. I think it encourages our developers to become better writers with guidance from the docs team. While ensuring docs are proposed prior to merging the implementation cross-repository is totally possible, I think #1 makes that flow easier.
Thanks for putting together the options, Alex. On Tue, May 23, 2017 at 11:02 AM, Ildiko Vancsa <[email protected]> wrote: > 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: [email protected]?subject:unsubscribe > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
