Open Stack

As a side-effect of working on the community training docs, we felt a simple, very specific version of the docs how to was required. It seems likely that we will incorporate the docs how to into the training itself. The idea being that learning to bug fix the docs is a good first step before learning to bug fix code. It will also make new devs first learn the docs before jumping into one of the projects.

So for question 7, i'd like to figure out how to integrate the doc boot camp material and sessions into the training we are putting together. It would be inspired!


Sean Roberts
Infrastructure Strategy
seanrob at yahoo-inc.com<mailto:seanrob at yahoo-inc.com> (925) 980-4729

On Jul 8, 2013, at 11:58 AM, Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>>
 wrote:

No responses here? I'd love to hear your thoughts.


On Thu, Jun 27, 2013 at 2:39 PM, Anne Gentle <anne at openstack.org<mailto:anne at openstack.org>> wrote:

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

_______________________________________________
Openstack-docs mailing list
Openstack-docs at lists.openstack.org<mailto:Openstack-docs at lists.openstack.org>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130708/69923ae0/attachment.html>