On Tue, May 23, 2017 at 8:56 AM, Zane Bitter <zbit...@redhat.com> wrote:
> 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. What prevents you from publishing to a different location? The landing page or the URL or something else I'm not considering? The URL can be changed in the publish job, I think, so what we really need are the "rules" and organization. I already discovered at the PTG that we are not consistent with version number and translation language in our URLs... It's something we'll have to work on -- the usability of the landing pages and the directories for the publish jobs and how those translate to URLs. Thoughts? Anne > > > 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 > -- Read my blog: justwrite.click <https://justwriteclick.com> Subscribe to Docs|Code: docslikecode.com
__________________________________________________________________________ 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