Open Stack

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.

Steve