<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 23, 2017 at 8:56 AM, Zane Bitter <span dir="ltr"><<a href="mailto:zbitter@redhat.com" target="_blank">zbitter@redhat.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">On 22/05/17 05:39, Alexandra Settle wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
1. We could combine all of the documentation builds, so that each<br>
project has a single doc/source directory that includes developer,<br>
contributor, and user documentation. This option would reduce the number<br>
of build jobs we have to run, and cut down on the number of separate<br>
sphinx configurations in each repository. It would completely change the<br>
way we publish the results, though, and we would need to set up<br>
redirects from all of the existing locations to the new locations and<br>
move all of the existing documentation under the new structure.<br>
</blockquote>
<br></span>
+0 in the short term, +1 for the long term<span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
2. We could retain the existing trees for developer and API docs, and<br>
add a new one for "user" documentation. The installation guide,<br>
configuration guide, and admin guide would move here for all projects.<br>
Neutron's user documentation would include the current networking guide<br>
as well. This option would add 1 new build to each repository, but would<br>
allow us to easily roll out the change with less disruption in the way<br>
the site is organized and published, so there would be less work in the<br>
short term.<br>
</blockquote>
<br></span>
+1, at least in the short term<br>
<br>
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.</blockquote><div><br></div><div>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... </div><div><br></div><div>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?</div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
3. We could do option 2, but use a separate repository for the new<br>
user-oriented documentation. This would allow project teams to delegate<br>
management of the documentation to a separate review project-sub-team,<br>
but would complicate the process of landing code and documentation<br>
updates together so that the docs are always up to date.<br>
</blockquote>
<br></span>
-1 for the reasons above.<br>
<br>
cheers,<br>
Zane.<div class="HOEnZb"><div class="h5"><br>
<br>
______________________________<wbr>______________________________<wbr>______________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" rel="noreferrer" target="_blank">OpenStack-dev-request@lists.op<wbr>enstack.org?subject:unsubscrib<wbr>e</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi<wbr>-bin/mailman/listinfo/openstac<wbr>k-dev</a><br>
</div></div></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div dir="ltr"><div dir="ltr"><div><br></div><div>Read my blog: <a href="https://justwriteclick.com" target="_blank">justwrite.click</a></div><div>Subscribe to Docs|Code: <a href="http://docslikecode.com" target="_blank">docslikecode.com</a> </div></div></div></div></div></div></div>
</div></div>