Open Stack

On 22/05/17 05:39, Alexandra Settle wrote:
> 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.

+0 in the short term, +1 for the long term

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

+1, at least in the short term

As we've been discussing since the summit, Heat has a bunch of 
documentation (specifically the Template Guide) that is end-user-facing 
but needs to be generated from the Heat repo (because it uses 
introspection on the code). Right now it's buried in the (OpenStack) 
developer-facing documentation, which is not very discoverable for end 
users. So generating the user guide from the project repos would allow 
us to move the Template Guide.

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

-1 for the reasons above.

cheers,
Zane.