<div dir="ltr">Thanks Nermina for the report! <div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Jul 25, 2013 at 10:16 PM, Nermina Miller <span dir="ltr"><<a href="mailto:nmiller@mirantis.com" target="_blank">nmiller@mirantis.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><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></div></div></div></blockquote><div><br></div><div style>I think it's okay if we don't segment further. We already have detailed segments in developers - Python Dev (not users of OpenStack but builders of the software), API Application Devs (who are end-users consuming APIs). So Administrators (end-users running clouds) can remain unsegmented. </div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div dir="ltr">
<div><div></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></div></div></div></blockquote><div><br></div><div style>I don't think manual indexes are a high priority when the doc bug backlog is as long as it is. But this is good feedback.</div><div> </div>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div dir="ltr"><div>
<div></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></div></div></div></blockquote><div><br></div><div style>I've talked to a Swift contributor, Chuck Thier, who would like to help. With now 12 projects needing documentation, I think we can do a few things to help out:</div>
<div style>1. Appoint a doc liason from each project.</div><div style>2. Ensure projects know how to update their admin guides. If they want to move project admin guides to their own repos, they could do that. </div><div style>
3. I also have to say, though, that don't think we can keep all docs everywhere updated. So we need to set expectations and coach projects to help get the best doc results.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_quote"><div dir="ltr"><div><div></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></div></div></div></blockquote><div><br></div><div style>I think this need is filled with the Operations Guide and Install Guide (choose-your-own-adventure). I think the Operations Guide and upcoming Admin User Guide can be combined to fill this need.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div dir="ltr">
<div><div></div><div>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></div></div></div></blockquote><div><br></div><div style>Hm. Which Steve is this? Do they mean core or integrated or both? Here's the list of projects:</div><div style><div>__CORE PROJECTS__</div>
<div>Compute (Nova)</div><div>Object Storage (Swift)</div><div>Image Service (Glance)</div><div>Identity (Keystone)</div><div>Dashboard (Horizon)</div><div>Networking (Neutron)</div><div>Block Storage (Cinder)</div><div>
<br>
</div><div>__INTEGRATED PROJECTS__</div><div>Metering/Monitoring (Ceilometer)</div><div>Orchestration (Heat)</div><div>Database Service (Trove)</div><div>Bare metal (Ironic)</div><div><br></div><div style>I want to hear more about this.</div>
</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote">
<div dir="ltr"><div><div></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></div></div></div></blockquote><div><br></div><div style>I think we do this by reducing scope. Probably this means only releasing Install and Config on release day, continually releasing everything else.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote"><div dir="ltr">
<div><div><br></div><div>* Split them to make them more modular.</div></div></div></div></div></blockquote><div><br></div><div style>Agreed, and we have a great start at the splits.</div><div style> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_quote"><div dir="ltr"><div><div><br>
</div><div>* Enable automatic generation of various documents.</div></div></div></div></div></blockquote><div><br></div><div style>Yes -- we need helpers to run and test <a href="https://review.openstack.org/#/c/35726/">https://review.openstack.org/#/c/35726/</a>. I can't get it to run for Neutron or Cinder. Anyone who can help, please jump in.</div>
<div style> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_quote">
<div dir="ltr"><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>- 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></div></div></div></blockquote><div><br></div>Design issues are being addressed with a designer from the Foundation. But I do not want to conflate the issues of design/presentation and consistency and released/archived information. These are separate goals with different solutions for each.</div>
<div class="gmail_quote"><br></div><div class="gmail_quote">Search results are controlled with the Google Custom Search Engine, documented on the wiki at <a href="https://wiki.openstack.org/wiki/Documentation/Release#Update_Google_site_map_and_Google_Custom_Search_Engine">https://wiki.openstack.org/wiki/Documentation/Release#Update_Google_site_map_and_Google_Custom_Search_Engine</a>. This step requires the use of a Google account that administers the paid Custom Search Engine. Currently Anne Gentle and Todd Morey have these credentials. At release time the doc release manager (me) does multiple steps, two of which control search findings:<br>
<br> - Ensure that the sitemap.xml stored on the web server contains links to the latest release. Using <a href="http://www.freesitemapgenerator.com">http://www.freesitemapgenerator.com</a>, it's an online generator tool with a 5,000 page limit.<br>
- Ensure that the past release site is removed from the Google Custom Search engine.<div> </div><div style>I have a bug logged against the doc build tool requesting that the sitemap.xml be rebuilt each build rather than manually each release. <a href="https://bugs.launchpad.net/openstack-manuals/+bug/1206220">https://bugs.launchpad.net/openstack-manuals/+bug/1206220</a> </div>
<div style><br></div><div style>If you think there are further steps to take, and you know what searches are causing consternation, report them so we can troubleshoot further. </div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_quote"><div dir="ltr"><div><div></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></div></div>
</blockquote><div><br></div><div style>Appreciate this work, thanks very much!</div><div style>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_quote"><div dir="ltr"><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><br></div></div></div></div></div></div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div></div>