Open Stack

On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at 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 <shardy at 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 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/20140523/8aef212a/attachment.html>