Open Stack

Hi Anne,
Not sure if any of this is what you were wanting, but what the heck:

1. Developer motivation:  Do or say everything on the assumption that 
they are passionate about their creation, then learn everything you can 
about it to get passionate with them. Any dialogue after that will only 
be positive. (writer experience)
3. As a reader, I would expect consistency across projects. If only 
because this makes it easier to search and understand.
4. As a new reader/user, I would prioritize overarching over project 
docs. OpenStack is a system made up of components, and I'd need to 
understand and use the system (and would assume that the system docs 
would help me do that in a way that the project docs could not).
     I'm assuming here that the majority of users go to the docs site to 
put together a cloud, and not just to use individual components. It 
would be interesting to see whether your web stats could show initial 
search paths through the docs site.
6. As a first-timer to the OpenStack project, the more information the 
better. I'm not sure in-person training sessions are necessary, but info 
on how the collaboration process works in general would be great.  The 
how-to-do-docs info page is great; I've set up the technical pieces. 
It's the next step of where-to-start-without-stepping-on-toes bit that 
would be good. Especially if you're a writer interested in the project 
and wanting to contribute, rather than a developer with a specific 
module in mind (read, me).
7. As a reader, I definitely prefer documentation written by the folks 
who wrote the software. That said, I'll use anything I can get if I'm 
trying to understand something (stackoverflow, blogs). As a writer, I only:

  * Quote for conceptual or general information if the organization is
    well-known and the link is likely to stay in place for at least a year.
  * Quote for specific information on software if written by the
    releasing organization.
  * Release if the process of
    draft-techreview-rewrite-techRereview-finalEdit.. is followed
    (together with following standards, company layouts, etc).

cheers,
Summer

> 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
> 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/20130709/74c9d74a/attachment.html>