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