<div dir="ltr">I'm in favor of option #1. I think it encourages our developers to become better writers with guidance from the docs team. While ensuring docs are proposed prior to merging the implementation cross-repository is totally possible, I think #1 makes that flow easier.<div><br></div><div>Thanks for putting together the options, Alex.</div></div><div class="gmail_extra"><br><div class="gmail_quote">On Tue, May 23, 2017 at 11:02 AM, Ildiko Vancsa <span dir="ltr"><<a href="mailto:ildiko.vancsa@gmail.com" target="_blank">ildiko.vancsa@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi Alex,<br>
<br>
First of all thank you for writing this up the summary and list options with their expected impacts.<br>
<span class=""><br>
><br>
> 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.<br>
><br>
</span><span class="">> 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.<br>
<br>
</span>I’m fully in favor for option #1 and/or option #2. From the perspective of trying to move step-by-step and give a chance to project teams to acclimatize with the changes I think starting with #2 should be sufficient.<br>
<br>
Although if we think that option #1 is doable as a starting point and also end goal, you have my support for that too.<br>
<span class=""><br>
><br>
> 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.<br>
><br>
<br>
</span>As being one of the advocates on having the documentation living together with the code so we can give a chance to the experts of the code changes to add the corresponding documentation as well, I'm definitely against option #3. :)<br>
<br>
Thanks and Best Regards,<br>
<div class="HOEnZb"><div class="h5">Ildikó<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.<wbr>openstack.org?subject:<wbr>unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-dev</a><br>
</div></div></blockquote></div><br></div>