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-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
