Open Stack

On Wed, May 7, 2014 at 1:43 PM, Roger Luethi <rl at patchworkscience.org>wrote:

> On Wed, 07 May 2014 09:16:48 -0700, Anne Gentle wrote:
> > Why not? The responses to my recent survey about doc contributions
> indicate
> > that the top barriers to docs’ contributions are:
> >
> > - Tools: DocBook and WADL are difficult
>
> DocBook may be a pain to set up, but editing DocBook documents is hardly
> more difficult than Markdown, RST or any other solution will be by the time
> you have added all the features you want to have.
>

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.

I'd like to stick to discussion of the requirements. I just named two
possible requirements, should those be included as well?

Thanks for the input Roger, you're exactly who we're trying to reach out to
for docs, and your input is super valuable.

Anne


>
> Formatting docs is hard because the style guides demand that numerous
> rules be considered. Ditching DocBook won't change that.
>
> > - Subject-matter expertise: People do not have test environments and they
> > feel that they don't know enough to contribute. Also, 70% of the
> > respondents to the survey work on or consume OpenStack fewer than 10
> hours
> > a week.
>
> The people who are qualified to contribute to the docs are usually not
> non-technical people, but they can't spend hours setting up an environment
> just to work on docs. IMHO good documentation (or scripts, or VM downloads)
> that make it easy to create a complete, working environment for testing and
> building documentation would go a long way towards making contributions
> easier.
>
> Roger
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140508/b4237916/attachment.html>