On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis <sean.mcgin...@gmx.com> wrote:
> 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. > Hey Sean, is the "right to merge" the top difficulty you envision with 1 or 2? Or is it finding people to do the writing and reviews? Curious about your thoughts and if you have some experience with specific day-to-day behavior here, I would love your insights. Anne > > > 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 > -- Read my blog: justwrite.click <https://justwriteclick.com> Subscribe to Docs|Code: docslikecode.com
__________________________________________________________________________ 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