Open Stack

On 05/08/2014 09:42 AM, Anne Gentle wrote:
> 
> 
> 
> On Wed, May 7, 2014 at 1:43 PM, Roger Luethi <rl at patchworkscience.org
> <mailto: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.

+1.  Anything that can be done to reduce the barrier to entry for doc
contributions would really help.  I think that it would also ease the
burden on the existing doc folks too, as they wouldn't be answering the
same questions on how to get started for new doc contributors.

-NGK

> 
>     Roger
> 
> 
> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>