Open Stack

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.

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.

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

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

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.

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.

* Split them to make them more modular.

* Enable automatic generation of various documents.

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

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.

Thanks!

Nermina

1
http://www.openstack.org/summit/portland-2013/session-videos/presentation/openstack-user-committee-update-and-survey-results
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20130725/bc96e048/attachment.html>