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?
