Open Stack

On Mon, May 22, 2017 at 5:41 PM, Sean McGinnis <sean.mcginnis at 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-request at 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-request at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170522/06dab286/attachment.html>