Le 2014-05-23 15:57, Anne Gentle a écrit :
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?
Yes, I can look into that.
The idea would be to generate some docbook from RST... So why not do it
for the whole to-be-written heat user guide in that case?
What I get from this thread is that 1) docbook is the best format to
use to generate a nice and feature-rich output, 2) developers don't want
to write docbook. Without being able to handle a different format
developers will no contribute, which is bad because they want, and we
want them to contribute :)
So my feeling is that we should work on the tools to convert RST (or
whatever format, but RST seems to be the "norm" for openstack projects)
to docbook, and generate our online documentation from there. There are
tools that can help us doing that, and I don't see an other solution
that would make us move forward.
Anne, you talked about experimenting with the end user guide, and after
the discussion and the technical info brought by Doug, Steve and Steven,
I now think it is worth trying.
Thoughts?
Gauvain
_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
