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