<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, May 7, 2014 at 1:43 PM, Roger Luethi <span dir="ltr"><<a href="mailto:rl@patchworkscience.org" target="_blank">rl@patchworkscience.org</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="">On Wed, 07 May 2014 09:16:48 -0700, Anne Gentle wrote:<br>
> Why not? The responses to my recent survey about doc contributions indicate<br>
> that the top barriers to docs’ contributions are:<br>
><br>
> - Tools: DocBook and WADL are difficult<br>
<br>
</div>DocBook may be a pain to set up, but editing DocBook documents is hardly<br>
more difficult than Markdown, RST or any other solution will be by the time<br>
you have added all the features you want to have.<br></blockquote><div><br></div><div>Yep, I realize DocBook fulfills many if not all of the requirements, plus it's what's used within much of RedHat and we have a translation toolchain built for it. These are compelling except for the survey results indicating it's a barrier. </div>

<div><br></div><div>I'd like to stick to discussion of the requirements. I just named two possible requirements, should those be included as well? </div><div><br></div><div>Thanks for the input Roger, you're exactly who we're trying to reach out to for docs, and your input is super valuable.</div>

<div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Formatting docs is hard because the style guides demand that numerous<br>
rules be considered. Ditching DocBook won't change that.<br>
<div class=""><br>
> - Subject-matter expertise: People do not have test environments and they<br>
> feel that they don't know enough to contribute. Also, 70% of the<br>
> respondents to the survey work on or consume OpenStack fewer than 10 hours<br>
> a week.<br>
<br>
</div>The people who are qualified to contribute to the docs are usually not<br>
non-technical people, but they can't spend hours setting up an environment<br>
just to work on docs. IMHO good documentation (or scripts, or VM downloads)<br>
that make it easy to create a complete, working environment for testing and<br>
building documentation would go a long way towards making contributions<br>
easier.<br>
<span class="HOEnZb"><font color="#888888"><br>
Roger<br>
</font></span></blockquote></div><br></div></div>