Open Stack

Le 2014-05-23 15:57, Anne Gentle a écrit :
> On Fri, May 23, 2014 at 8:42 AM, Steven Hardy <shardy at 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 <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.
>> 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