<div dir="ltr"><div class="gmail_quote">Hi, everyone, here's the audience report Anne mentioned in the latest edition of "What's Up, Doc?" I'm looking forward to your comments :)<div dir="ltr"><div><br>
</div><div><div>This report is a result of: </div><div><br></div><div>- The review of OpenStack User Committee Update & Survey Results [1]</div><div>- Interviews with doc bug submitters, Steve Gordon, and Tom Fifield, OpenStack Foundation Community Manager</div>
<div>- A search of Ask OpenStack.</div>
<div><br></div><div>USER GROUPS</div><div>According to the User Committee, there are three general OpenStack user groups:</div><div><br></div><div>* A consumer, who is submitting work, storing data, or interacting with an OpenStack cloud.</div>

<div><br></div><div>* An operator, who is running a public or private OpenStack cloud.</div><div><br></div><div>* An ecosystem partner, who is developing solutions such as software and services around OpenStack. This corresponds to the “built for OpenStack” trademark requirements. </div>

<div><br></div><div>* A distribution provider or application vendor, who is providing packaged solutions and support of OpenStack.</div><div><br></div><div>OBSERVATION:<span style="white-space:pre-wrap">       </span>It seems like, in general IT terms, they are talking about an end-user, administrator, developer, and vendor. In a general IT environment, that would warrant creating an end-user, administrator, and developer guides. In that environment, an administrator is capable of installing, managing, and troubleshooting a system, so the respective guide would contain all of that information, including network and security setup, management, and troubleshooting.</div>

<div><br></div><div>According to Tom, the operators are system administrators and network/storage operators. He also indicates that there may be some developers who are also operators.</div><div><br></div><div>It seems that the operator is the same as the administrator; however, the missing link here is the further info that the User Committee collected based on their 400+ surveys, which may reveal further operator segmentation. From the users I interviewed, there was just not enough info to make that determination. They were developers interested in API reference, installation, network setup and integration, and object store info.</div>

<div><br></div><div>DOCUMENTATION FEEDBACK</div><div>In the Portland Summit presentation, the group indicates that there has been quite a bit of feedback about documentation, which is not fully captured in the provided documents (i.e., the slideshow, the Google docs).</div>

<div><br></div><div>What they do say is that there is a need to archive the old content and create an end-user guide and a troubleshooting guide.</div><div><br></div><div>Based on the answers I gathered from doc bug submitters and the ask forum, the need is not to provide more documentation but provide easy ways to find the information, mark documentation as archived, and provide the latest documentation:</div>

<div><br></div><div>* In one particular comment, a user says they printed out one of the OpenStack documents in the PDF format but couldn't find indexes at the end as in other booklike documents. He also says that the ToC was not well organized or presented.</div>

<div><br></div><div>* Another user says that having it all unified would be nice if it made keeping the docs up to date easier. He says that people manage to dig up some old, wrong documentation sometimes, and then it shows up in #openstack-swift with broken setups that they want help debugging. </div>

<div><br></div><div>* For another user, having a consolidated admin manual would be useful because it would enable to include more demo setups—show how the bits and pieces fit together.</div><div><br></div><div style>Steve says that to him <span style="font-family:arial,sans-serif;font-size:13px">as a deployer it is more important that the depth of coverage of each project is consistent, </span><span style="font-family:arial,sans-serif;font-size:13px">regardless whether the guides are all in one or separate</span><span style="font-family:arial,sans-serif;font-size:13px">.</span></div>
<div><br></div><div>According to Tom, there are issues with accuracy and completeness and that the goal should be to:</div>
<div><br></div><div>* Make the documentation more sustainable and reduce the amount of effort required to produce the 6-monthly release docs.</div><div><br></div><div>* Split them to make them more modular.</div><div><br>

</div><div>* Enable automatic generation of various documents.</div><div><br></div><div>RECOMMENDED NEXT STEPS</div><div>I think the key here is to access and analyze the survey results from the User Committee and plan the restructure efforts according to the needs of that audience. That might mean organizing another survey with open-ended and specific questions to see what exactly they do and what they’d like to see in the documentation. However, some common necessary steps seem to be that:</div>

<div><br></div><div>- The old documentation should be archived</div><div>- The duplicate information should be removed</div><div style>- The content should be made consistent</div><div>- The search should be improved so the old documentation doesn't show up in the results</div>

<div><br></div><div>One personal documentation usability observation/recommendation would be to organize the content in the format MSDN Library uses and allow the users to print on paper or PDF whatever they need. That would also mean creating ToCs that open to intro pages explaining the hierarchy and the available topics, and individual pages that contain See Also pages. There should be no pages that only have a single line of text with a subhead. </div>

<div><br></div></div><div class="gmail_extra">Now, I know I was supposed to look into the audience but you got a bit of documentation info as well :) Looking forward to your feedback and next tasks.</div><div class="gmail_extra">

<br></div><div class="gmail_extra">Thanks!</div><div class="gmail_extra"><br></div><div class="gmail_extra">Nermina</div><div class="gmail_extra"><br></div><div class="gmail_extra">1 <a href="http://www.openstack.org/summit/portland-2013/session-videos/presentation/openstack-user-committee-update-and-survey-results" target="_blank">http://www.openstack.org/summit/portland-2013/session-videos/presentation/openstack-user-committee-update-and-survey-results</a><div>
<div class="h5"><br></div></div></div></div></div></div>