[openstack-dev] [doc][ptls][all] Documentation publishing future

Doug Hellmann doug at doughellmann.com
Mon May 22 18:38:37 UTC 2017

Excerpts from Anne Gentle's message of 2017-05-22 12:36:29 -0500:
> > On May 22, 2017, at 9:09 AM, Doug Hellmann <doug at doughellmann.com> wrote:
> >
> > Excerpts from Dmitry Tantsur's message of 2017-05-22 12:26:25 +0200:
> >>> On 05/22/2017 11:39 AM, Alexandra Settle wrote:
> >>> Hi everyone,
> >>>
> >>> The documentation team are rapidly losing key contributors and core reviewers.
> >>> We are not alone, this is happening across the board. It is making things
> >>> harder, but not impossible.
> >>>
> >>> Since our inception in 2010, we’ve been climbing higher and higher trying to
> >>> achieve the best documentation we could, and uphold our high standards. This is
> >>> something to be incredibly proud of.
> >>>
> >>> However, we now need to take a step back and realise that the amount of work we
> >>> are attempting to maintain is now out of reach for the team size that we have.
> >>> At the moment we have 13 cores, of whom none are full time contributors or
> >>> reviewers. This includes myself.
> >>>
> >>> Until this point, the documentation team has owned several manuals that include
> >>> content related to multiple projects, including an installation guide, admin
> >>> guide, configuration guide, networking guide, and security guide. Because the
> >>> team no longer has the resources to own that content, we want to invert the
> >>> relationship between the doc team and project teams, so that we become liaisons
> >>> to help with maintenance instead of asking for project teams to provide liaisons
> >>> to help with content. As a part of that change, we plan to move the existing
> >>> content out of the central manuals repository, into repositories owned by the
> >>> appropriate project teams. Project teams will then own the content and the
> >>> documentation team will assist by managing the build tools, helping with writing
> >>> guidelines and style, but not writing the bulk of the text.
> >>>
> >>> We currently have the infrastructure set up to empower project teams to manage
> >>> their own documentation in their own tree, and many do. As part of this change,
> >>> the rest of the existing content from the install guide and admin guide will
> >>> also move into project-owned repositories. We have a few options for how to
> >>> implement the move, and that's where we need feedback now.
> >>>
> >>> 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.
> >>>
> >>> 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?
> >>
> >> We're already hosting install-guide and api-ref in our tree, and I'd prefer we
> >> don't change it, as it's going to be annoying (especially wrt backports). I'd
> >> prefer we create user-guide directory in projects, and move the user guide there.
> >
> > Handling backports with a merged guide is an issue we didn't come
> > up with in our earlier discussions. How often do you backport doc
> > changes in practice? Do you foresee merge conflicts caused by issues
> > other than the files being renamed?
> >
> For the user guide, we currently intend there to be no backports, and
> ask that the writing reflect supported releases. (Thinking that any
> person walking up to an OpenStack cloud service to use it may not have
> control over which version is installed.)

OK, that's good to know. If we end up combining all of the guides into a
single build, I think we would have to end up supporting publishing
series-specific versions of all of them to support the installation and
configuration cases. That doesn't necessarily mean that we have to
encourage backports to the other guides, though.

> Only three docs are currently published for each release: install
> guide, networking guide, and the configuration reference. To answer
> the "how often" for those three guides, looks like about a dozen a
> month that are content related and not translation related for all
> three guides. https://review.openstack.org/#/q/project:openstack/openstack-manuals+branch:stable/ocata
> and https://review.openstack.org/#/q/project:openstack/openstack-manuals+branch:stable/newton

That's a large enough number that I think we want to arrange things to
avoid issues with backports, at least to start.

> Merge conflicts can be a mitigated risk for docs -- and renames are
> low-risk since we have redirects.
> Let me know if I'm missing anything or misrepresenting what's reality.
> Anne
> > Doug
> >
> > __________________________________________________________________________
> > 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

More information about the OpenStack-dev mailing list