Open Stack

On Tue, May 23, 2017 at 8:56 AM, Zane Bitter <zbitter at 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-request at 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20170523/3d9938d7/attachment.html>