Re: [Openstack-doc-core] Documentation accuracy rating
Great input, more comments below. On Tue, May 15, 2012 at 9:49 AM, Razique Mahroua razique.mahr...@gmail.comwrote: Thanks for the informations, please see my comments Anne Gentle a...@openstack.org 7 mai 2012 22:32 Ok, that makes perfect sense to me. I'll do a first pass. Here are some things that stick out of me from the last five months of analytics. - The Starter Guide for Diablo still gets a huge number of hits. It's also a popular landing page That guide will be updated for Essex this week. I expect a similar trend. Let's hope the rework we will do around the landing page and within the guide would keep it well demanded. I'm almost done with the validation of the CSSCorp guide, after that, I'll test that one also from scratch. You probably don't need to do that - it has been updated as bugs are logged against it. And how many people are installing Diablo at this point? Probably not many? Swift still contains, as Keystone when it arrived, much complicated both concepts AND words (much more than keystone in fact : reaper, auditor, accounter, replicas, zones, weight, etc...) Maybe as we did for KS, a schema would present it. I myself need to learn more from it, I'll work on a schema as I did for Keystone. You're correct about the vocabulary hurdle... how about adding these to the /doc/src/docbkx/common/glossary.xml file? There's a bug where a little more work needs to be done to get the glossary to output correctly, see https://bugs.launchpad.net/openstack-manuals/+bug/985944. - The new reference listing of all 467 nova config options is sporting a 74% bounce rate. My guess is that it doesn't offer enough information really about configuration, but someone searched for the option name and only found that page. Since there are still 4-5 doc bugs remaining about how to configure nova, this is also not surprising. From that page visitors try other pages about configuring specific parts of Compute, like the API, so I think work spent there would be well spent. What page is it ? I think there are several, not sure about that It's at http://docs.openstack.org/essex/openstack-compute/admin/content/compute-options-reference.html. - To your credit Razique, the new multi-nic page is doing very well in the stats. Lots of visitors, less than 50% bounce rate. I think it would get a kick-ass section rating! Thanks, I think the schema helps I do realize a high bounce rate might be a good thing, that people find what they need and move on. I'm looking for topics where I don't think they're finding what they need. What i like is the ability for the reader to leave comments. Is it possible for me to get notified when a comment is published for a given page ? We could also update the doc and triage the bugs based on user requests Yes, absolutely! Go to disqus.com and get a username, then send it to me. I'll add you as a moderator, and you can adjust your settings for notifications. You can also subscribe to the RSS feeds for each Disqus ID, such as http://openstackinstall.disqus.com/latest.rss or http://openstackdocs.disqus.com/latest.rss. VNC and volumes are both highly visited topics. That is a great news, both used to be undocumented compared to other topics :) I'm surprised the networking topics aren't more visited. Perhaps they're not as findable? Seems like people are always asking about it on the list. Network is a real challenge when it comes to deployment. I remember one asking for extra network deployment scenario. Even if we provide much infos about it, it is never enough. Something might be missing, extra schemes, definitions maybe ? Honestly the feedback I hear is that people try to install without knowing their network configuration - there's a lot of hidden network configurations in different places. Here are the top 25 search terms on docs.openstack.org (the top search field): keystone quantum dashboard swift nova architecture diablo essex vmware api nova configuration nova-manage restart all services install Quantum snapshot vnc installation network kvm live migration nova-manage nova.conf scheduler ubuntu windows I hope this is helpful and close to what you were originally seeking. We can revisit in 3 months and see how trends are looking. There are two ways to interpret that list, the first one being the hot topics - KS, Quantum, Horizon, based on the news, the upcoming features, the OPS capabilities The second one being... elements for which we lack of extra informations about. Why nova-manage restart all services is in that list ? or even live migration (that one is pretty interesting architecture, ). Hm, yep, lots of interpretations. Thanks for reading all the way through! Anne postbox-contact.jpg-- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
Re: [Openstack-doc-core] Documentation accuracy rating
Ok, that makes perfect sense to me. I'll do a first pass. Here are some things that stick out of me from the last five months of analytics. - The Starter Guide for Diablo still gets a huge number of hits. It's also a popular landing page That guide will be updated for Essex this week. I expect a similar trend. - The Compute Admin guide (trunk or diablo) is the next most popular landing page. I think people are returning to it, and they usually read 10-12 page per visit. - The Object Storage Admin guide has the highest bounce rate pages in it. The ring causes confusion, object replication has high bounce, it's also possible that they think Object Storage is actually block storage, which it's not. There are doc bugs logged against this guide so it's not surprising but a good second set of info. - The new reference listing of all 467 nova config options is sporting a 74% bounce rate. My guess is that it doesn't offer enough information really about configuration, but someone searched for the option name and only found that page. Since there are still 4-5 doc bugs remaining about how to configure nova, this is also not surprising. From that page visitors try other pages about configuring specific parts of Compute, like the API, so I think work spent there would be well spent. - To your credit Razique, the new multi-nic page is doing very well in the stats. Lots of visitors, less than 50% bounce rate. I think it would get a kick-ass section rating! I do realize a high bounce rate might be a good thing, that people find what they need and move on. I'm looking for topics where I don't think they're finding what they need. VNC and volumes are both highly visited topics. I'm surprised the networking topics aren't more visited. Perhaps they're not as findable? Seems like people are always asking about it on the list. Here are the top 25 search terms on docs.openstack.org (the top search field): keystone quantum dashboard swift nova architecture diablo essex vmware api nova configuration nova-manage restart all services install Quantum snapshot vnc installation network kvm live migration nova-manage nova.conf scheduler ubuntu windows I hope this is helpful and close to what you were originally seeking. We can revisit in 3 months and see how trends are looking. Thanks, Anne On Sun, May 6, 2012 at 7:05 PM, Lorin Hochstein lo...@nimbisservices.comwrote: Hi Anne: It's good to know the analytics data is there if we want to dig deeper. However, until somebody working on docs starts asking specific analytics-driven questions about the site usage, it's probably not worth setting up an automatic report emailed to the team. At least, I know I wouldn't spend much time looking at the report... Take care, Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis Services, Inc. www.nimbisservices.com On May 4, 2012, at 10:00 AM, Anne Gentle wrote: Hi all - Not a silly idea at all. We've had a request to the doc tools team for a while to get ratings on pages - annotations would be another great step. How to take action... so we did make the Cloud doc tool plugin open source before the summit. The first priority to me is to get anchor tags on api.openstack.org, and I've asked Matt Stephenson to take that on. Can we find another Java programmer who would like to work on a user story like one of these: As a reader of the OpenStack documentation, I'd like to quickly log a bug against a page that's out-dated. As a reader of the OpenStack documentation, I'd like to make a quick vote on how effective the page is. Joe Savak, can you put these request into the tracking system you want to use for the Cloud docs plugin? It can be openstack-manuals if you want. As for analytics, I've attached the weekly report. We've been collecting data since the site started and I find it informative but of course you have to interpret. I could set up the report to be emailed to this list weekly. What do you think? I can also do customized reports for particular pages or sections (volumes, networking, and so on). Thanks, Anne On Thu, May 3, 2012 at 1:32 PM, Lorin Hochstein lo...@nimbisservices.comwrote: On May 3, 2012, at 10:15 AM, Razique Mahroua wrote: Hey there, just had that silly idea : is it possible to rank/ note some part of the documentations ? The logic here is to gather from readers what are the pages they often read, and how much accurate they are . That would help to update the doc bugs importance, and also know for the docs what the readers are expecting from it : - incomplete sections - false directions - outdated examples - kick-ass section etc... Maybe I'm just rambling, possible I'd love a lightweight mechanism for annotating the documentation, where I can do something equivalent to taking a red pen, circling some text, and writing a comment in the margin. Also, As I recall from the summit, we also discussed collecting
Re: [Openstack-doc-core] Documentation accuracy rating
Hi Anne: It's good to know the analytics data is there if we want to dig deeper. However, until somebody working on docs starts asking specific analytics-driven questions about the site usage, it's probably not worth setting up an automatic report emailed to the team. At least, I know I wouldn't spend much time looking at the report... Take care, Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis Services, Inc. www.nimbisservices.com On May 4, 2012, at 10:00 AM, Anne Gentle wrote: Hi all - Not a silly idea at all. We've had a request to the doc tools team for a while to get ratings on pages - annotations would be another great step. How to take action... so we did make the Cloud doc tool plugin open source before the summit. The first priority to me is to get anchor tags on api.openstack.org, and I've asked Matt Stephenson to take that on. Can we find another Java programmer who would like to work on a user story like one of these: As a reader of the OpenStack documentation, I'd like to quickly log a bug against a page that's out-dated. As a reader of the OpenStack documentation, I'd like to make a quick vote on how effective the page is. Joe Savak, can you put these request into the tracking system you want to use for the Cloud docs plugin? It can be openstack-manuals if you want. As for analytics, I've attached the weekly report. We've been collecting data since the site started and I find it informative but of course you have to interpret. I could set up the report to be emailed to this list weekly. What do you think? I can also do customized reports for particular pages or sections (volumes, networking, and so on). Thanks, Anne On Thu, May 3, 2012 at 1:32 PM, Lorin Hochstein lo...@nimbisservices.com wrote: On May 3, 2012, at 10:15 AM, Razique Mahroua wrote: Hey there, just had that silly idea : is it possible to rank/ note some part of the documentations ? The logic here is to gather from readers what are the pages they often read, and how much accurate they are . That would help to update the doc bugs importance, and also know for the docs what the readers are expecting from it : - incomplete sections - false directions - outdated examples - kick-ass section etc... Maybe I'm just rambling, possible I'd love a lightweight mechanism for annotating the documentation, where I can do something equivalent to taking a red pen, circling some text, and writing a comment in the margin. Also, As I recall from the summit, we also discussed collecting Google Analytics data on the HTML documentation hosted on docs.openstack.org(?). (I can't remember the outcome of that, though). Take care, Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis Services, Inc. www.nimbisservices.com -- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp Analytics_docs.openstack.org_20120423-20120429_(Weekly_Google_analytics_report).pdf smime.p7s Description: S/MIME cryptographic signature -- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
Re: [Openstack-doc-core] Documentation accuracy rating
On May 3, 2012, at 10:15 AM, Razique Mahroua wrote: Hey there, just had that silly idea : is it possible to rank/ note some part of the documentations ? The logic here is to gather from readers what are the pages they often read, and how much accurate they are . That would help to update the doc bugs importance, and also know for the docs what the readers are expecting from it : - incomplete sections - false directions - outdated examples - kick-ass section etc... Maybe I'm just rambling, possible I'd love a lightweight mechanism for annotating the documentation, where I can do something equivalent to taking a red pen, circling some text, and writing a comment in the margin. Also, As I recall from the summit, we also discussed collecting Google Analytics data on the HTML documentation hosted on docs.openstack.org(?). (I can't remember the outcome of that, though). Take care, Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis Services, Inc. www.nimbisservices.com smime.p7s Description: S/MIME cryptographic signature -- Mailing list: https://launchpad.net/~openstack-doc-core Post to : openstack-doc-core@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack-doc-core More help : https://help.launchpad.net/ListHelp
