Open Stack

On 23/05/14 06:38, 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.

I mostly agree with this. DocBook is actually not too bad to write (I 
say this as a non-fan of XML), and it is by far the most expressive 
markup language. For the kinds of use cases typical of documentation (to 
take one example, marking which parts of example commands are 
substitutable) you can't really beat it. I've tried a lot of markup 
languages, and even written one, but they can only be simpler that 
DocBook when they're adapted to support only particular use cases that 
are less complex than the ones we have.

I may be misremembering, but I seem to recall that the docs produced 
with the proprietary tool that I forget the name of have some 
idiosyncratic formatting (in terms of the locations of line breaks &c.) 
that is very difficult to match by hand. People are going to refer to 
the existing source as a guide to what to do, and if it looks really 
hard to duplicate that is one barrier to entry.

> 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,

This is definitely a great improvement. It's only part of the solution 
though - if developers were using the gate to run PEP8 instead of 
running it locally, I would tell them to stop wasting my time, since 
everybody on the review list gets 3 new emails each time they upload a 
patchset to fix some whitespace problem. What you need when you're 
editing a complex markup language manually is a fast feedback loop, and 
uploading a new patchset to Gerrit is not that.

Last time I looked at this stuff, it involved spending several hours 
trying to install the Java tools, and culminated in me giving up and 
just shipping the patch and hoping someone else would notice if they 
didn't work (IIRC this was actually creating the WADLs for the Heat API, 
and miraculously they did work).

IMHO this remains a huge barrier to anyone getting started who is not 
exceptionally motivated (by which I mean contributing to OpenStack docs 
is more or less their full time job). Ideally we would have something as 
simple as, or preferably simpler than, running unit tests with tox to 
rapidly build the docs without performing a huge local installation. (I 
don't know what the solution here looks like though... maybe a doc 
building service?)

cheers,
Zane.