<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">Hi Anne,<br>
Not sure if any of this is what you were wanting, but what the
heck:<br>
<br>
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)<br>
3. As a reader, I would expect consistency across projects. If
only because this makes it easier to search and understand. <br>
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). <br>
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. <br>
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).<br>
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:<br>
<ul>
<li>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.</li>
<li>Quote for specific information on software if written by the
releasing organization.<br>
</li>
<li>Release if the process of
draft-techreview-rewrite-techRereview-finalEdit.. is followed
(together with following standards, company layouts, etc). <br>
</li>
</ul>
cheers, <br>
Summer<br>
<br>
</div>
<blockquote
cite="mid:CAD0KtVFbTnpq5PcMN0WEsJypMvGwAJKthbVQdkzgqc9VrA9czQ@mail.gmail.com"
type="cite">
<div dir="ltr">No responses here? I'd love to hear your thoughts. </div>
<div class="gmail_extra"><br>
<br>
<div class="gmail_quote">On Thu, Jun 27, 2013 at 2:39 PM, Anne
Gentle <span dir="ltr"><<a moz-do-not-send="true"
href="mailto:anne@openstack.org" target="_blank">anne@openstack.org</a>></span>
wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0
.8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr">
<p>Hi all -</p>
<p>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.<br>
</p>
<p>Specifically, here are some questions I want to ask all
of you for inspiration and ideas:</p>
<ol>
<li>What's the most important lesson you've learn about
motivating developers to write user documentation? Who
taught it to you and how? </li>
<li>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?</li>
<li>With the different projects under the OpenStack
umbrella, how much consistency would you expect to
see, project-to-project? </li>
<li>As a reader, would you prioritize project docs over
overarching docs or vice-versa? Why? </li>
<li>As a project maintainer, which docs would you value
more highly, combined solutions docs or docs specific
and detailed for your project? Why?</li>
<li>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?</li>
<li>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?"</li>
<li>What makes people in a community excited about
documentation? Successful outcomes? Camaraderie?
Speaking from a point of authority?</li>
</ol>
<p>Thanks all for your input — looking forward to
responses and being inspired while I drive
cross-country.</p>
<span class="HOEnZb"><font color="#888888">
<p>Anne<br>
</p>
</font></span></div>
</blockquote>
</div>
<br>
</div>
<br>
<fieldset class="mimeAttachmentHeader"></fieldset>
<br>
<pre wrap="">_______________________________________________
Openstack-docs mailing list
<a class="moz-txt-link-abbreviated" href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a>
<a class="moz-txt-link-freetext" href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a>
</pre>
</blockquote>
<br>
</body>
</html>