Open Stack

Thanks Nermina for the report!


On Thu, Jul 25, 2013 at 10:16 PM, Nermina Miller <nmiller at mirantis.com>wrote:

> 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 :)
>
> This report is a result of:
>
> - The review of OpenStack User Committee Update & Survey Results [1]
> - Interviews with doc bug submitters, Steve Gordon, and Tom Fifield,
> OpenStack Foundation Community Manager
> - A search of Ask OpenStack.
>
> USER GROUPS
> According to the User Committee, there are three general OpenStack user
> groups:
>
> * A consumer, who is submitting work, storing data, or interacting with an
> OpenStack cloud.
>
> * An operator, who is running a public or private OpenStack cloud.
>
> * An ecosystem partner, who is developing solutions such as software and
> services around OpenStack. This corresponds to the “built for OpenStack”
> trademark requirements.
>
> * A distribution provider or application vendor, who is providing packaged
> solutions and support of OpenStack.
>
> OBSERVATION: 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.
>
> 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.
>
> 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.
>
>
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.


> DOCUMENTATION FEEDBACK
> 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).
>
> 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.
>
> 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:
>
> * 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.
>
>
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.


> * 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.
>
>
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:
1. Appoint a doc liason from each project.
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.
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.


> * 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.
>
>
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.


> Steve says that to him as a deployer it is more important that the depth
> of coverage of each project is consistent, regardless whether the guides
> are all in one or separate.
>
>
Hm. Which Steve is this? Do they mean core or integrated or both? Here's
the list of projects:
__CORE PROJECTS__
Compute (Nova)
Object Storage (Swift)
Image Service (Glance)
Identity (Keystone)
Dashboard (Horizon)
Networking (Neutron)
Block Storage (Cinder)

__INTEGRATED PROJECTS__
Metering/Monitoring (Ceilometer)
Orchestration (Heat)
Database Service (Trove)
Bare metal (Ironic)

I want to hear more about this.


> According to Tom, there are issues with accuracy and completeness and that
> the goal should be to:
>
> * Make the documentation more sustainable and reduce the amount of effort
> required to produce the 6-monthly release docs.
>

I think we do this by reducing scope. Probably this means only releasing
Install and Config on release day, continually releasing everything else.


>
> * Split them to make them more modular.
>

Agreed, and we have a great start at the splits.


>
> * Enable automatic generation of various documents.
>

Yes -- we need helpers to run and test
https://review.openstack.org/#/c/35726/. I can't get it to run for Neutron
or Cinder. Anyone who can help, please jump in.


>
> RECOMMENDED NEXT STEPS
> 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:
>
> - The old documentation should be archived
> - The duplicate information should be removed
> - The content should be made consistent
> - The search should be improved so the old documentation doesn't show up
> in the results
>
>
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.

Search results are controlled with the Google Custom Search Engine,
documented on the wiki at
https://wiki.openstack.org/wiki/Documentation/Release#Update_Google_site_map_and_Google_Custom_Search_Engine.
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:

 - Ensure that the sitemap.xml stored on the web server contains links to
the latest release. Using http://www.freesitemapgenerator.com, it's an
online generator tool with a 5,000 page limit.
 - Ensure that the past release site is removed from the Google Custom
Search engine.

I have a bug logged against the doc build tool requesting that the
sitemap.xml be rebuilt each build rather than manually each release.
https://bugs.launchpad.net/openstack-manuals/+bug/1206220

If you think there are further steps to take, and you know what searches
are causing consternation, report them so we can troubleshoot further.

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.
>
> 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.
>

Appreciate this work, thanks very much!
Anne


>
> Thanks!
>
> Nermina
>
> 1
> http://www.openstack.org/summit/portland-2013/session-videos/presentation/openstack-user-committee-update-and-survey-results
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130729/0dc4f767/attachment-0001.html>