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

Akilesh K akilesh1597 at gmail.com
Mon Oct 6 05:23:33 UTC 2014


Can someone create a Wiki for all the options available to contribute to
openstack docs. I have a personel feeling that ArchWiki
<https://wiki.archlinux.org/index.php/Main_page> is one of the best
technical documentations available and they even have wiki for guidelines
for writing.

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

On Mon, Oct 6, 2014 at 10:35 AM, Gauvain Pocentek <
gauvain.pocentek at objectif-libre.com> wrote:

> Le 2014-10-06 05:26, Tom Fifield a écrit :
>
>> 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>> 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>, 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.
>>
>
> 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.
>
> 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.
>
> I'd really like to see this process extended to a larger part of the
> documentation, although this might not be needed everywhere.
>
> I had this workflow in mind:
>
> * a dev sends a review to a temporary repo
> * other devs can validate the information, and give their +1 when the
> patch is ready
> * a doc reviewer either requests more technical detail, or gives his
> +2/accept
> * the doc team reworks the patch and integrates it to the doc repository
>
> 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).
>
> As a side note, we have a tool that converts RST to docbook. The hot guide
> is automatically built using this tool (http://docs.openstack.org/
> hot-guide/content/hot_guide_hot-guide.html).
>
> Gauvain
>
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141006/11b705c1/attachment.html>


More information about the OpenStack-dev mailing list