Excerpts from Anne Gentle's message of 2017-05-22 12:36:29 -0500: > > On May 22, 2017, at 9:09 AM, Doug Hellmann <d...@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-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
