Open Stack

On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli <stefano at openstack.org>
wrote:

> hi Nick,
>
> On 09/29/2014 02:06 PM, Nicholas Chase wrote:
> > Because we know that the networking documentation needs particular
> > attention, we're starting there.  We have a Networking Guide, from which
> > we will ultimately pull information to improve the networking section of
> > the admin guide.
>
> I love experiments and I appreciate your effort to improve the
> situation. It's not clear to me what the experiment wants to demonstrate
> and I'd appreciate more details.
>

Absolutely.


>
> > The preliminary Table of Contents is here:
> > https://wiki.openstack.org/wiki/NetworkingGuide/TOC , and the
> > instructions for contributing are as follows:
>
> This is cool and I see there is a blueprint also assigned
>
> https://blueprints.launchpad.net/openstack-manuals/+spec/create-networking-guide


Correct.


>
>
> >  1. Pick an existing topic or create a new topic. For new topics, we're
> >     primarily interested in deployment scenarios.
> >  2. Develop content (text and/or diagrams) in a format that supports at
> >     least basic markup (e.g., titles, paragraphs, lists, etc.).
> >  3. Provide a link to the content (e.g., gist on github.com, wiki page,
> >     blog post, etc.) under the associated topic.
>
> Points 1-3 seem to be oriented at removing Launchpad from the equation.
> Is that all there is? I guess it makes sense to remove obstacles,
> although editing the wiki (since it requires a launchpad account anyway)
> may not be the best way to track progress and see assignments.
>

No, really, the main change is in step 5.  Launchpad isn't the problem, as
far as we can tell; Docbook is.


>
> >  4. Send e-mail to reviewers networking at openstacknow.com.
>
> Why not use the docs mailing list or other facilities on @openstack.org?
> Who is responding to that address?
>

If someone want to provide us a list on @openstack.org, 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. :)

People on the alias are myself, Edgar Magana, Matt Kasawara, Phil Hopkins,
Anne Gentle, and Elke Vorheis.


>
> >  5. A writer turns the content into an actual patch, with tracking bug,
> >     and docs reviewers (and the original author, we would hope) make
> >     sure it gets reviewed and merged.
>
> This is puzzling: initially I thought that you had some experimental
> magic software that would monitor edits to the wiki TOC page, go grab
> html content from gist, blog post, etc, transform that into docbook or
> something similar and magically create a task on LP for a doc writer to
> touch up and send for review.
>

Wouldn't THAT be fantastic.  No, unfortunately not.  This is a process
experiment, rather than a technology experiment.


> My understanding is that the Docs team has been using bug reports on
> Launchpad to receive contributions and a writer would pick them from the
> list, taking care of the transformation to docbook and gerrit workflow.
>

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)?"


> Point 5. makes the experiment look like the process already in place,
> only using a wiki page first (instead of a blueprint first) and a
> private email address instead of a public bug tracker.
>

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.


> Have I got it wrong? Can you explain a bit more why this experiment is
> not using the existing process? What is the experiment trying to
> demonstrate?
>

The experiment is trying to determine whether we can increase the level of
developer participation in the docs process by removing the hurtles of:

1)  Deciphering where in the docs repo content goes
2)  Learning XML in general, and Docbook in particular
3)  Figuring out how to get docs to build
4)  And so on, until the additions are actually merged

Does that clear it up?

Thanks...

----  Nick


>
> /stef
>
> --
> Ask and answer questions on https://ask.openstack.org
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141003/d420da95/attachment.html>