<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <span dir="ltr"><<a href="mailto:shardy@redhat.com" target="_blank">shardy@redhat.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="">On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote:<br>


> On 05/23/2014 12:13 PM, Steven Hardy wrote:<br>
> > [...]<br>
> > I'll hold my hand up as one developer who tried to contribute but ran away<br>
> > screaming due to all the XML-java-ness of the current process.<br>
> ><br>
> > I don't think markup complexity is a major barrier to contribution. Needing<br>
> > to use a closed source editor and download unfathomably huge amounts of<br>
> > java to build locally definitely are though IMO/IME.<br>
><br>
> You do not need a closed sourced editor for XML - I'm using emacs and<br>
> others in the team use vi for it.<br>
<br>
</div>Sure, maybe "need" was the wrong word to use, my apologies.  Regardless,<br>
the docs refer to a closed source tool being "encouraged", which<br>
immediately discouraged me when trying to figure out the workflow.<br>
<br>
I've tried editing XML in vim a few times, and although it's obviously<br>
possible, it's far less painful when I'm dealing with other more<br>
human-friendly formats.<br>
<div class=""><br>
> Yes, it downloads a lot Java once. We also now build the documents as<br>
> part of the gate, so you can also check changes by clicking the<br>
> "checkbuild" target, it will show you the converted books,<br>
<br>
</div>Sure, that's good, but my (and I'd guess many others) preference is for<br>
formats which can be easily built locally with only distro-provided tools,<br>
not a huge pile of third party java.<br>
<br>
Not trying to start a format-advocacy argument here, just trying to provide<br>
a data-point that, if the success criteria is developer participation in<br>
the docs process, then the current toolchain is definitely a barrier to<br>
participation for some potential contributors.<br></blockquote><div><br></div><div><br class="">Thanks for the discussions -- let's keep a tone of civility. Understand that doc writers have specific tools that work well for them. That said, we do want to collaborate more with our end users specifically.<br>

</div><div><br></div><div>Yes, a barrier to entry due to XML allergies is exactly what we're exploring here. However I will say it's not DocBook that causes most people the vehement reaction you're having, Steve, it's more typically a reaction to WADL. But I want to start somewhere.</div>

<div><br></div><div>All, is the end user guide a good place to experiment with a simpler markdown source? Is there another book or audience that would be a better starting point? I'm also thinking the <a href="http://developer.openstack.org">developer.openstack.org</a> content would be a good experimental area.</div>

<div>Thanks, </div><div>Anne</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
Steve<br>
<div class=""><div class="h5"><br>
_______________________________________________<br>
OpenStack-dev mailing list<br>
<a href="mailto:OpenStack-dev@lists.openstack.org">OpenStack-dev@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</div></div></blockquote></div><br></div></div>