<div dir="ltr"><div>Can someone create a Wiki for all the options available to contribute to openstack docs. I have a personel feeling that <a href="https://wiki.archlinux.org/index.php/Main_page">ArchWiki<span id="goog_2042528517"></span><span id="goog_2042528518"></span></a> is one of the best technical documentations available and they even have wiki for guidelines for writing. <br><br></div>Can the the documentation process be open to all and then the admins can decide on what changes to accept and what to revert. s<br></div><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Oct 6, 2014 at 10:35 AM, Gauvain Pocentek <span dir="ltr"><<a href="mailto:gauvain.pocentek@objectif-libre.com" target="_blank">gauvain.pocentek@objectif-libre.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Le 2014-10-06 05:26, Tom Fifield a écrit :<span class=""><br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
On 04/10/14 04:03, Nick Chase wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli <<a href="mailto:stefano@openstack.org" target="_blank">stefano@openstack.org</a><br>
<mailto:<a href="mailto:stefano@openstack.org" target="_blank">stefano@openstack.org</a>><u></u>> wrote:<br>
> 1. Pick an existing topic or create a new topic. For new topics,<br>
we're<br>
> primarily interested in deployment scenarios.<br>
> 2. Develop content (text and/or diagrams) in a format that<br>
supports at<br>
> least basic markup (e.g., titles, paragraphs, lists, etc.).<br>
> 3. Provide a link to the content (e.g., gist on <a href="http://github.com" target="_blank">github.com</a><br>
<<a href="http://github.com" target="_blank">http://github.com</a>>, wiki page,<br>
> blog post, etc.) under the associated topic.<br>
<br>
Points 1-3 seem to be oriented at removing Launchpad from the equation.<br>
Is that all there is? I guess it makes sense to remove obstacles,<br>
although editing the wiki (since it requires a launchpad account anyway)<br>
may not be the best way to track progress and see assignments.<br>
<br>
<br>
No, really, the main change is in step 5. Launchpad isn't the problem,<br>
as far as we can tell; Docbook is.<br>
</blockquote>
<br>
Hi Nick,<br>
<br>
As best I can tell - 'step 5' has been in place for at least the last<br>
few summits at least, so this is not a change :) We have had a policy<br>
where anyone can dump text in bug reports and we'll wrangle it. This has<br>
been popular, see eg Marco Cossoni's contributions, but in my opinion<br>
not widely enough communicated - so thanks for your efforts.<br>
</blockquote>
<br></span>
We actually have another way to work with developers, although it's been only available for the new HOT guide. This guide is temporary, it will become a part of the user guide. The interesting point is that it's written in RST, and uses gerrit for reviews. So far we've had 2 core members of the heat team contributing content, and this content has been reviewed by other members of the team.<br>
<br>
The devs patches focused on content, not on the form of the content. I suggested to accept the patches rapidly - as long as they're technically correct - and to rework them later (what I've started to do a couple days ago). The fact that we're using gerrit and that the developers review each other work makes me more comfortable with the quality of the content.<br>
<br>
I'd really like to see this process extended to a larger part of the documentation, although this might not be needed everywhere.<br>
<br>
I had this workflow in mind:<br>
<br>
* a dev sends a review to a temporary repo<br>
* other devs can validate the information, and give their +1 when the patch is ready<br>
* a doc reviewer either requests more technical detail, or gives his +2/accept<br>
* the doc team reworks the patch and integrates it to the doc repository<br>
<br>
I really think that the process worked for the HOT guide, and I'm convinced that it could work for other parts of the doc (Cinder and Neutron drivers doc for instance).<br>
<br>
As a side note, we have a tool that converts RST to docbook. The hot guide is automatically built using this tool (<a href="http://docs.openstack.org/hot-guide/content/hot_guide_hot-guide.html" target="_blank">http://docs.openstack.org/<u></u>hot-guide/content/hot_guide_<u></u>hot-guide.html</a>).<span class="HOEnZb"><font color="#888888"><br>
<br>
Gauvain</font></span><div class="HOEnZb"><div class="h5"><br>
<br>
______________________________<u></u>_________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org" target="_blank">OpenStack-dev@lists.openstack.<u></u>org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/<u></u>cgi-bin/mailman/listinfo/<u></u>openstack-dev</a><br>
</div></div></blockquote></div><br></div>