<div dir="ltr"><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli <span dir="ltr"><<a href="mailto:stefano@openstack.org" target="_blank">stefano@openstack.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">hi Nick,<br>
<span class=""><br>
On 09/29/2014 02:06 PM, Nicholas Chase wrote:<br>
> Because we know that the networking documentation needs particular<br>
> attention, we're starting there.  We have a Networking Guide, from which<br>
> we will ultimately pull information to improve the networking section of<br>
> the admin guide.<br>
<br>
</span>I love experiments and I appreciate your effort to improve the<br>
situation. It's not clear to me what the experiment wants to demonstrate<br>
and I'd appreciate more details.<br></blockquote><div><br></div><div>Absolutely.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<span class=""><br>
> The preliminary Table of Contents is here:<br>
> <a href="https://wiki.openstack.org/wiki/NetworkingGuide/TOC" target="_blank">https://wiki.openstack.org/wiki/NetworkingGuide/TOC</a> , and the<br>
> instructions for contributing are as follows:<br>
<br>
</span>This is cool and I see there is a blueprint also assigned<br>
<a href="https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide</a></blockquote><div><br></div><div>Correct.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
<br>
>  1. Pick an existing topic or create a new topic. For new topics, we're<br>
<span class="">>     primarily interested in deployment scenarios.<br>
</span>>  2. Develop content (text and/or diagrams) in a format that supports at<br>
<span class="">>     least basic markup (e.g., titles, paragraphs, lists, etc.).<br>
</span>>  3. Provide a link to the content (e.g., gist on <a href="http://github.com" target="_blank">github.com</a>, wiki page,<br>
<span class="">>     blog post, etc.) under the associated topic.<br>
<br>
</span>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></blockquote><div><br></div><div>No, really, the main change is in step 5.  Launchpad isn't the problem, as far as we can tell; Docbook is.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
>  4. Send e-mail to reviewers <a href="mailto:networking@openstacknow.com">networking@openstacknow.com</a>.<br>
<br>
Why not use the docs mailing list or other facilities on @<a href="http://openstack.org" target="_blank">openstack.org</a>?<br>
Who is responding to that address?<br></blockquote><div><br></div><div>If someone want to provide us a list on @<a href="http://openstack.org">openstack.org</a>, that'd be awesome.  I set up this address because I control the forwarding and could do it immediately without having to ask for anyone's approval. :)  </div><div><br></div><div>People on the alias are myself, Edgar Magana, Matt Kasawara, Phil Hopkins, Anne Gentle, and Elke Vorheis.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
>  5. A writer turns the content into an actual patch, with tracking bug,<br>
<span class="">>     and docs reviewers (and the original author, we would hope) make<br>
>     sure it gets reviewed and merged.<br>
<br>
</span>This is puzzling: initially I thought that you had some experimental<br>
magic software that would monitor edits to the wiki TOC page, go grab<br>
html content from gist, blog post, etc, transform that into docbook or<br>
something similar and magically create a task on LP for a doc writer to<br>
touch up and send for review.<br></blockquote><div><br></div><div>Wouldn't THAT be fantastic.  No, unfortunately not.  This is a process experiment, rather than a technology experiment.</div><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
My understanding is that the Docs team has been using bug reports on<br>
Launchpad to receive contributions and a writer would pick them from the<br>
list, taking care of the transformation to docbook and gerrit workflow.<br></blockquote><div><br></div><div>Bug reports are great, and we do want to continue getting those -- and the more information for the writer, the better! -- but that's a process where the developer says, "hey, I think you should write something about X".  This is the opposite.  We're saying, "Hey, we want to write about X, does anybody have any resources?  Or if you think we should write about Y, do you have something already fleshed out (versus a paragraph you'd add in a bug report)?"</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Point 5. makes the experiment look like the process already in place,<br>
only using a wiki page first (instead of a blueprint first) and a<br>
private email address instead of a public bug tracker.<br></blockquote><div><br></div><div>Well, you're half-right.  It's like the process in already in place, only using a wiki page first and having a dedicated writer pick a developer's brain and actually produce the prose and put it into Docbook, rather than holding a gun to the developer's head and forcing him or her to write Docbook in order to contribute to the docs.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Have I got it wrong? Can you explain a bit more why this experiment is<br>
not using the existing process? What is the experiment trying to<br>
demonstrate?<br></blockquote><div><br></div><div>The experiment is trying to determine whether we can increase the level of developer participation in the docs process by removing the hurtles of:</div><div><br></div><div>1)  Deciphering where in the docs repo content goes</div><div>2)  Learning XML in general, and Docbook in particular</div><div>3)  Figuring out how to get docs to build</div><div>4)  And so on, until the additions are actually merged</div><div><br></div><div>Does that clear it up?</div><div><br></div><div>Thanks...</div><div><br></div><div>----  Nick</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
/stef<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
Ask and answer questions on <a href="https://ask.openstack.org" target="_blank">https://ask.openstack.org</a><br>
</font></span></blockquote></div><br></div></div>