Open Stack

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.

Yes, a barrier to entry due to XML allergies is exactly what we're
exploring here. However I will say it's not DocBook that causes most people
the vehement reaction you're having, Steve, it's more typically a reaction
to WADL. But I want to start somewhere.

All, is the end user guide a good place to experiment with a simpler
markdown source? Is there another book or audience that would be a better
starting point? I'm also thinking the developer.openstack.org content would
be a good experimental area.
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/e01cc08f/attachment.html>