Open Stack

Excerpts from Dmitry Tantsur's message of 2017-05-22 16:54:30 +0200:
> On 05/22/2017 04:09 PM, Doug Hellmann 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?
> 
> When we created our in-tree install-guide, we backported the whole of it to the 
> previous release :)
> 
> But mostly, I expect that if a bug fix requires a change to install-guide (the 
> bug is in install-guide itself, or we need to document a know issue, or 
> anything), it has to be backportable.

Sure. I'm curious about how often that has come up in the past, as a way
to predict how big of an issue it is likely to be in the future.

Doug

> 
> Files being renamed can already be an issue (sometimes git suddenly chokes on 
> them). Anyway, currently we're in process of refactoring our install-guide, so 
> backports may be hard anyway.
> 
> > 
> > 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
> > 
>