<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, May 23, 2014 at 8:42 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:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote:<br>
> On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <<a href="mailto:shardy@redhat.com">shardy@redhat.com</a>> wrote:<br>
><br>
> > 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<br>
> > 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.<br>
> > 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>
> > 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>
> ><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>
> > 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>
> ><br>
><br>
><br>
> Thanks for the discussions -- let's keep a tone of civility. Understand<br>
> that doc writers have specific tools that work well for them. That said, we<br>
> do want to collaborate more with our end users specifically.<br>
<br>
</div></div>My apologies if my remarks have been interpreted as uncivil, that was<br>
definitely not my intention.<br>
<br></blockquote><div><br></div><div>Oh no not at all, sorry -- my intent is that we are all staying civil and it's good. :)</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">


The only point I really wanted to convey was +1 on trying out an easier<br>
markup, and thanks for bringing up the topic of a user orientated<br>
orchestration guide - I would definitely like to contribute to the effort.<br>
<div class="HOEnZb"><div class="h5"><br></div></div></blockquote><div><br></div><div>So we're still a little stuck on the tradeoffs -- with easier markup we lose some features. </div><div><br></div><div>For other generated reference docs, we maintain a set of python scripts in openstack-doc-tools. Is it possible for someone to look into generating the Heat template reference information outside of Sphinx?</div>

<div>Thanks,</div><div>Anne</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="HOEnZb"><div class="h5">
Steve<br>
<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>