Open Stack

Thanks for your excellent report Nermina. I agree with all the conclusions.

Regards,

Tom

On 25/07/13 20:16, Nermina Miller 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.
> 
> 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
> 
> 
> 
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>