On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <sha...@redhat.com> wrote:
> On Fri, May 23, 2014 at 08:09:06AM -0500, Anne Gentle wrote: > > On Fri, May 23, 2014 at 6:19 AM, Steven Hardy <sha...@redhat.com> wrote: > > > > > On Fri, May 23, 2014 at 12:38:40PM +0200, Andreas Jaeger wrote: > > > > On 05/23/2014 12:13 PM, Steven Hardy wrote: > > > > > [...] > > > > > I'll hold my hand up as one developer who tried to contribute but > ran > > > away > > > > > screaming due to all the XML-java-ness of the current process. > > > > > > > > > > I don't think markup complexity is a major barrier to contribution. > > > Needing > > > > > to use a closed source editor and download unfathomably huge > amounts of > > > > > java to build locally definitely are though IMO/IME. > > > > > > > > You do not need a closed sourced editor for XML - I'm using emacs and > > > > others in the team use vi for it. > > > > > > Sure, maybe "need" was the wrong word to use, my apologies. > Regardless, > > > the docs refer to a closed source tool being "encouraged", which > > > immediately discouraged me when trying to figure out the workflow. > > > > > > I've tried editing XML in vim a few times, and although it's obviously > > > possible, it's far less painful when I'm dealing with other more > > > human-friendly formats. > > > > > > > Yes, it downloads a lot Java once. We also now build the documents as > > > > part of the gate, so you can also check changes by clicking the > > > > "checkbuild" target, it will show you the converted books, > > > > > > Sure, that's good, but my (and I'd guess many others) preference is for > > > formats which can be easily built locally with only distro-provided > tools, > > > not a huge pile of third party java. > > > > > > Not trying to start a format-advocacy argument here, just trying to > provide > > > a data-point that, if the success criteria is developer participation > in > > > the docs process, then the current toolchain is definitely a barrier to > > > participation for some potential contributors. > > > > > > > > > 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. > > My apologies if my remarks have been interpreted as uncivil, that was > definitely not my intention. > > Oh no not at all, sorry -- my intent is that we are all staying civil and it's good. :) > The only point I really wanted to convey was +1 on trying out an easier > markup, and thanks for bringing up the topic of a user orientated > orchestration guide - I would definitely like to contribute to the effort. > > So we're still a little stuck on the tradeoffs -- with easier markup we lose some features. 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? Thanks, Anne > Steve > > _______________________________________________ > OpenStack-dev mailing list > OpenStack-dev@lists.openstack.org > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
_______________________________________________ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev