[Openstack-docs] [openstack-dev] Contributing to docs without Docbook -- YES you can!

Tom Fifield tom at openstack.org
Mon Oct 6 03:59:49 UTC 2014


On 06/10/14 11:38, Nick Chase wrote:
> On Sun, Oct 5, 2014 at 11:26 PM, Tom Fifield <tom at openstack.org
> <mailto:tom at openstack.org>> wrote:
> 
>     On 04/10/14 04:03, Nick Chase wrote:
>     >
>     > On Fri, Oct 3, 2014 at 3:07 PM, Stefano Maffulli <stefano at openstack.org <mailto:stefano at openstack.org>
>     > <mailto:stefano at openstack.org <mailto:stefano at openstack.org>>> wrote:
>     >     >  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 <http://github.com>
>     >     <http://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.
> 
>     Hi Nick,
> 
>     As best I can tell - 'step 5' has been in place for at least the last
>     few summits at least, so this is not a change :) We have had a policy
>     where anyone can dump text in bug reports and we'll wrangle it. This has
>     been popular, see eg Marco Cossoni's contributions, but in my opinion
>     not widely enough communicated - so thanks for your efforts.
> 
> 
> Right, again, it's fantastic that people can dump text in bug reports,
> and yes, it's probably not well known.  We're just trying to sort of
> widen out what people are sending from a few paragraphs to entire
> topics.  But hey, the general idea is the same. We're all trying to get
> to the same point.
> 
> Obviously there's something about the current process that's not working
> as well as it could.  This experiment is about trying to figure out
> what.  If all we're changing is moving the contribution point from a bug
> report to a wiki, then great; having just one changed variable among
> control variables is good science.
>  
> 
> 
>     >     >  4. Send e-mail to reviewers networking at openstacknow.com <mailto:networking at openstacknow.com>
>     >     <mailto:networking at openstacknow.com
>     <mailto:networking at openstacknow.com>>.
>     >
>     >     Why not use the docs mailing list or other facilities on
>     >     @openstack.org <http://openstack.org> <http://openstack.org>?
>     >     Who is responding to that address?
>     >
>     >
>     > If someone want to provide us a list on @openstack.org <http://openstack.org>
>     > <http://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.
> 
>     I find it quite odd that the larger team is being excluded from this
>     effort. Why would it need a separate mailing list?
> 
> 
> We haven't intentionally excluded anybody; we were just keeping it small
> both to keep it a focused effort -- this way we could more easily hash
> things out without anybody stepping on anybody else -- and so that we
> weren't essentially volunteering people against their will. :) But we
> can easily change it over to the main docs list.

Yup - I think that would be more in the spirit of our Open Development
core principle and I would encourage you to do so.


Regards,

Tom




More information about the Openstack-docs mailing list