Open Stack

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.

> 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

>  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.

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

>  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.

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.

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.

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?

/stef

-- 
Ask and answer questions on https://ask.openstack.org