Open Stack

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.

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