Open Stack

Hi all -

With the new "programs" coming to OpenStack, some documentation will need
to be delivered on the same day as the release. We also now have 10
core/integrated projects with 2 more in incubation. Currently the
documentation that is delivered on the same day as the release is the
contributor docs, maintained by the Python devs (Sphinx/RST) and stored
with the code. We have separate repos for API docs and operator docs, but
the review processes are the same as the code. As you can imagine, I'm
looking for ideas for this brave new world.

Specifically, here are some questions I want to ask all of you for
inspiration and ideas:

   1. What's the most important lesson you've learn about motivating
   developers to write user documentation? Who taught it to you and how?
   2. What's the most difficult issue around documentation that you see
   over and over again in open source projects? How do people avoid it or fix
   it when it happens to them?
   3. With the different projects under the OpenStack umbrella, how much
   consistency would you expect to see, project-to-project?
   4. As a reader, would you prioritize project docs over overarching docs
   or vice-versa? Why?
   5. As a project maintainer, which docs would you value more highly,
   combined solutions docs or docs specific and detailed for your project? Why?
   6. Do you think people want in-person training sessions about how to
   write OpenStack docs? We're working on a doc boot camp with a day of
   teaching and a day of doing, what do you think is an important planning
   part of that? Who specifically would you invite?
   7. How important is "official" to you when it comes to project
   documentation, such as Python or Django? What editorial/review processes
   are in place to ensure a doc is considered "official?"
   8. What makes people in a community excited about documentation?
   Successful outcomes? Camaraderie? Speaking from a point of authority?

Thanks all for your input — looking forward to responses and being inspired
while I drive cross-country.

Anne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130627/da90ca6f/attachment.html>