Open Stack

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.

> 
> Cheers,
> 
> Alex
> 
> 
> 
> __________________________________________________________________________
> 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
>