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.
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
