Open Stack

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> 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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130708/22078e46/attachment.html>