Re: [openstack-dev] [Ceilometer] Documentation and patches
Anne Gentle wrote: Nova is the overall winner (cough) with 110 doc bugs followed by keystone with 26. 110 doc bugs indicates a serious need. Ouch. Teams, please follow through on docs and see how you can help. https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=nova https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=keystone https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=neutron https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=swift https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=glance https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=cinder https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=xen One way to raise awareness would be to crash the project-specific meetings and attract everyone's attention to those bugs, pasting the corresponding link. It just takes one doc-team member to be around, and should be more efficient than filing extra bugtasks or mentioning it on the release meeting (which is not attended by that many developers nowadays). Then nothing will beat getting personal, identifying the best person and tracking them down on IRC :) But that takes much more time. -- Thierry Carrez (ttx) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On Tue, Sep 3, 2013 at 10:14 AM, Thierry Carrez thie...@openstack.orgwrote: Anne Gentle wrote: Nova is the overall winner (cough) with 110 doc bugs followed by keystone with 26. 110 doc bugs indicates a serious need. Ouch. Teams, please follow through on docs and see how you can help. https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=nova https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=keystone https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=neutron https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=swift https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=glance https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=cinder https://bugs.launchpad.net/openstack-manuals/+bugs/?field.tag=xen One way to raise awareness would be to crash the project-specific meetings and attract everyone's attention to those bugs, pasting the corresponding link. It just takes one doc-team member to be around, and should be more efficient than filing extra bugtasks or mentioning it on the release meeting (which is not attended by that many developers nowadays). Then nothing will beat getting personal, identifying the best person and tracking them down on IRC :) But that takes much more time. Looking at the ical feed I know it's not possible for one person to be the doc nag if they want to get any other work done in a week as there are now nearly 30 hour-long meetings each week. :) One thought is to identify doc liaisons per project that serve the purpose of bringing docs up at each weekly meeting. https://wiki.openstack.org/wiki/Documentation/ProjectDocLeads Honestly, though, my sense is that the biggest difficulty is for devs to step back and look at the big picture of OpenStack and write docs that way. We also need more deployers writing docs for each other, and users writing docs for consuming OpenStack clouds. Ideas on enabling those writers are also welcome. Anne -- Thierry Carrez (ttx) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Anne Gentle annegen...@justwriteclick.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
Lorin Hochstein wrote: Would it help if doc bugs were associated with the relevant OpenStack project, in addition to the openstack-manauls project? For example, we could mark nova-related doc bugs as nova project bugs in addition to openstack-manuals project bugs. I'm not a big fan of this idea. The goal of task tracking is to have actionable tasks that can be completed by committing a solution to one given repository. So if the fix is supposed to land in an docs repo (and not, say, in the nova repo), then the bug should appear in the docs task tracking, and be automatically closed when the commit mentioning the bug lands into that repository. The problem if you add a 'nova' task for the same bug is that there will be no way of closing that bug automatically, since there is actually nothing to land in that repository. You're using task tracking to do a notification and an easy search for the developers. That is not what the 'project' means in task tracking. You're using a 'nova' task only to attract 'nova devs' attention. This makes the whole task tracking more inaccurate. I would rather use tagging to link a doc bug (or a QA bug) to a wanted audience, and encourage people to search for tasks being tagged with the name of their project, which is where their help is required. Or use subscription. Something that is linked to the people and not the code repository. -- Thierry Carrez (ttx) ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On Sat, Aug 31, 2013 at 9:09 AM, Lorin Hochstein lo...@nimbisservices.comwrote: On Fri, 30 Aug 2013 08:33:40 -0500, Anne Gentle wrote: I applaud Julien's note and we're happy to work with the teams on finding where docs should go. Julien's feeling very behind, and I'm sure other projects are feeling the same. We all have to set priorities. Here's where I'd start. Log doc bugs in openstack-manuals for: installation configuration day-to-day running end-user tasks admin tasks troubleshooting Log doc bugs in openstack-api-site for: API reference docs Would it help if doc bugs were associated with the relevant OpenStack project, in addition to the openstack-manauls project? For example, we could mark nova-related doc bugs as nova project bugs in addition to openstack-manuals project bugs. I like this idea and it seems fairly trivial to do automatically -- teams, unless you see a big problem with this approach I'll patch the DocImpact automation tool on Monday. Anne This would make outstanding doc issues more visible to the relevant devs, and would reinforce the idea that missing/incorrect documentation in, say, nova should be viewed as a *nova* issue and not simply a *documentation* issue. In particular, it could generate more doc-focused effort when it comes time for the pre-release bug squashing activities, since devs will be encouraged to squash those bugs in their project. Take care, Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis Services, Inc. www.nimbisservices.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Anne Gentle annegen...@justwriteclick.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On 01/09/13 23:02, Anne Gentle wrote: On Sat, Aug 31, 2013 at 9:09 AM, Lorin Hochstein lo...@nimbisservices.com mailto:lo...@nimbisservices.com wrote: On Fri, 30 Aug 2013 08:33:40 -0500, Anne Gentle wrote: I applaud Julien's note and we're happy to work with the teams on finding where docs should go. Julien's feeling very behind, and I'm sure other projects are feeling the same. We all have to set priorities. Here's where I'd start. Log doc bugs in openstack-manuals for: installation configuration day-to-day running end-user tasks admin tasks troubleshooting Log doc bugs in openstack-api-site for: API reference docs Would it help if doc bugs were associated with the relevant OpenStack project, in addition to the openstack-manauls project? For example, we could mark nova-related doc bugs as nova project bugs in addition to openstack-manuals project bugs. I like this idea and it seems fairly trivial to do automatically -- teams, unless you see a big problem with this approach I'll patch the DocImpact automation tool on Monday. ... and I'll do a manual update of the current bug list: https://launchpad.net/openstack-manuals/+milestone/havana https://launchpad.net/openstack-api-site/+milestone/havana which anyone is welcome to work on before then :) even just dumps of rant-y text in the bugs you care about welcome! Anne This would make outstanding doc issues more visible to the relevant devs, and would reinforce the idea that missing/incorrect documentation in, say, nova should be viewed as a *nova* issue and not simply a *documentation* issue. In particular, it could generate more doc-focused effort when it comes time for the pre-release bug squashing activities, since devs will be encouraged to squash those bugs in their project. Take care, Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis Services, Inc. www.nimbisservices.com https://www.nimbisservices.com/ ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org mailto:OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Anne Gentle annegen...@justwriteclick.com mailto:annegen...@justwriteclick.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
That makes a lot of sense. It's also a way to encourage low hanging fruit documentation for folks interested in a particular project. Otherwise, they are not very visible. - Brian Schott, CTO Nimbis Services, Inc. brian.sch...@nimbisservices.com ph: 443-274-6064 fx: 443-274-6060 On Aug 31, 2013, at 10:09 AM, Lorin Hochstein lo...@nimbisservices.com wrote: On Fri, 30 Aug 2013 08:33:40 -0500, Anne Gentle wrote: I applaud Julien's note and we're happy to work with the teams on finding where docs should go. Julien's feeling very behind, and I'm sure other projects are feeling the same. We all have to set priorities. Here's where I'd start. Log doc bugs in openstack-manuals for: installation configuration day-to-day running end-user tasks admin tasks troubleshooting Log doc bugs in openstack-api-site for: API reference docs Would it help if doc bugs were associated with the relevant OpenStack project, in addition to the openstack-manauls project? For example, we could mark nova-related doc bugs as nova project bugs in addition to openstack-manuals project bugs. This would make outstanding doc issues more visible to the relevant devs, and would reinforce the idea that missing/incorrect documentation in, say, nova should be viewed as a *nova* issue and not simply a *documentation* issue. In particular, it could generate more doc-focused effort when it comes time for the pre-release bug squashing activities, since devs will be encouraged to squash those bugs in their project. Take care, Lorin -- Lorin Hochstein Lead Architect - Cloud Services Nimbis Services, Inc. www.nimbisservices.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev smime.p7s Description: S/MIME cryptographic signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 08/30/2013 08:39 AM, Julien Danjou wrote: Hi team, We need to get better at documentation. We are terrible at it. We let code go through the gates knowing that our documentation isn't up to date. We have features implemented 6 months ago still not documented. Nobody's going to do it for us. Therefore I strongly suggest that as soon as you spot that the documentation must be updated to reflect any change, you score -1 the patchset to oblige the submitting developer to write some prose. This is something we could get better at across all of OpenStack. I've been thinking about proposing requiring docs *somewhere* for everything that affects docs. For small stuff, it could be explaining it especially well in the commit message. For larger stuff, it could be covered on the blueprint or wiki page. I think at the least, we could provide some of the core information so that the docs team is left with figuring out where best to fit it into the existing guides, as opposed to generating the content from scratch. - -- Russell Bryant -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.14 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iEYEARECAAYFAlIgl4wACgkQFg9ft4s9SAZxlACgq6BZVx8zW7XLxjis4FootwOD qCMAoI3ztfBMetE13TJ3ZjZ+sLaQVPrx =W0H0 -END PGP SIGNATURE- ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
How about mandating that when one adds a DocImpact in a review it should have a url to an etherpad/wiki with sufficient information for the doc team? yes, +1 to let docs team figure out where to fit it into existing guides. -- dims On Fri, Aug 30, 2013 at 9:01 AM, Russell Bryant rbry...@redhat.com wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 08/30/2013 08:39 AM, Julien Danjou wrote: Hi team, We need to get better at documentation. We are terrible at it. We let code go through the gates knowing that our documentation isn't up to date. We have features implemented 6 months ago still not documented. Nobody's going to do it for us. Therefore I strongly suggest that as soon as you spot that the documentation must be updated to reflect any change, you score -1 the patchset to oblige the submitting developer to write some prose. This is something we could get better at across all of OpenStack. I've been thinking about proposing requiring docs *somewhere* for everything that affects docs. For small stuff, it could be explaining it especially well in the commit message. For larger stuff, it could be covered on the blueprint or wiki page. I think at the least, we could provide some of the core information so that the docs team is left with figuring out where best to fit it into the existing guides, as opposed to generating the content from scratch. - -- Russell Bryant -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.14 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iEYEARECAAYFAlIgl4wACgkQFg9ft4s9SAZxlACgq6BZVx8zW7XLxjis4FootwOD qCMAoI3ztfBMetE13TJ3ZjZ+sLaQVPrx =W0H0 -END PGP SIGNATURE- ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Davanum Srinivas :: http://davanum.wordpress.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On Fri, Aug 30 2013, Russell Bryant wrote: This is something we could get better at across all of OpenStack. I've been thinking about proposing requiring docs *somewhere* for everything that affects docs. For small stuff, it could be explaining it especially well in the commit message. For larger stuff, it could be covered on the blueprint or wiki page. I think at the least, we could provide some of the core information so that the docs team is left with figuring out where best to fit it into the existing guides, as opposed to generating the content from scratch. I was discussing the subject with Anne on IRC. Ceilometer doesn't have any documentation stored in any external repository (yet). My point of view is that it's better to systematically block patches not updating the documentation, than to use DocImpact and cross fingers. That clearly didn't work for us so far. I'll try to check about how we can integrate with the existing documentation provided by other core projects (such as API references etc) while keeping the documentation in the repository. Any hint appreciated obviously. :) -- Julien Danjou ;; Free Software hacker ; independent consultant ;; http://julien.danjou.info signature.asc Description: PGP signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On Fri, Aug 30 2013, Davanum Srinivas wrote: How about mandating that when one adds a DocImpact in a review it should have a url to an etherpad/wiki with sufficient information for the doc team? yes, +1 to let docs team figure out where to fit it into existing guides. That's a possibility. It still seems better to me to have the project's developers involved into the documentation than outsourcing it completely to another team. For example, there's no way to be sure the documentation team is going to understand what the developer meant on that wiki page, and that it'll then write correct instructions. Having the patches sent on the documented project directly makes sure developers are going to review it and that to the doc writer who's improving the documentation for example got things right. -- Julien Danjou -- Free Software hacker - independent consultant -- http://julien.danjou.info signature.asc Description: PGP signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On Fri, Aug 30, 2013 at 8:31 AM, Julien Danjou jul...@danjou.info wrote: On Fri, Aug 30 2013, Davanum Srinivas wrote: How about mandating that when one adds a DocImpact in a review it should have a url to an etherpad/wiki with sufficient information for the doc team? yes, +1 to let docs team figure out where to fit it into existing guides. That's a possibility. It still seems better to me to have the project's developers involved into the documentation than outsourcing it completely to another team. For example, there's no way to be sure the documentation team is going to understand what the developer meant on that wiki page, and that it'll then write correct instructions. While we do have a nice spike in new contributors to the OpenStack docs [1], we always have to refer to the original developer anyway, even with a detailed blueprint / wiki page. So be involved and be ready for questions from doc writers. Having the patches sent on the documented project directly makes sure developers are going to review it and that to the doc writer who's improving the documentation for example got things right. For integrated projects, this is certainly the way to go, as the docs program has had to draw the line at core. However, when people come to docs.openstack.org, they want OpenStack docs. We need to get projects fitting into the install guide, configuration guide, end user guide, admin user guide, and so on. I'd like as much integrated information in those as possible by October 17th. We do publish continuously so all the projects need to get better at continuously updating docs. I'd like to get docs closer to code all the time, but Sphinx hasn't met a few crucial requirements: translation, content reuse, PDF, and comment integration. I'd rather have repos and docs by audience than by project. To repeat, people come to docs.openstack.org for OpenStack docs. Let's make those better all the time. Thanks, Anne 1. https://github.com/openstack/openstack-manuals/graphs/contributors -- Julien Danjou -- Free Software hacker - independent consultant -- http://julien.danjou.info ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Anne Gentle annegen...@justwriteclick.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
I applaud Julien's note and we're happy to work with the teams on finding where docs should go. Julien's feeling very behind, and I'm sure other projects are feeling the same. We all have to set priorities. Here's where I'd start. Log doc bugs in openstack-manuals for: installation configuration day-to-day running end-user tasks admin tasks troubleshooting Log doc bugs in openstack-api-site for: API reference docs Ensure your configuration information is updated as it is now being scraped with a script to go into the Config Ref. Assign knowledgeable team members to the doc bugs. Come to #openstack-doc on IRC to ask which files to update. Recruit writers and reviewers. Go go go! Thanks, Anne On Fri, Aug 30, 2013 at 8:22 AM, Davanum Srinivas dava...@gmail.com wrote: How about mandating that when one adds a DocImpact in a review it should have a url to an etherpad/wiki with sufficient information for the doc team? yes, +1 to let docs team figure out where to fit it into existing guides. -- dims On Fri, Aug 30, 2013 at 9:01 AM, Russell Bryant rbry...@redhat.comwrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 08/30/2013 08:39 AM, Julien Danjou wrote: Hi team, We need to get better at documentation. We are terrible at it. We let code go through the gates knowing that our documentation isn't up to date. We have features implemented 6 months ago still not documented. Nobody's going to do it for us. Therefore I strongly suggest that as soon as you spot that the documentation must be updated to reflect any change, you score -1 the patchset to oblige the submitting developer to write some prose. This is something we could get better at across all of OpenStack. I've been thinking about proposing requiring docs *somewhere* for everything that affects docs. For small stuff, it could be explaining it especially well in the commit message. For larger stuff, it could be covered on the blueprint or wiki page. I think at the least, we could provide some of the core information so that the docs team is left with figuring out where best to fit it into the existing guides, as opposed to generating the content from scratch. - -- Russell Bryant -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.14 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iEYEARECAAYFAlIgl4wACgkQFg9ft4s9SAZxlACgq6BZVx8zW7XLxjis4FootwOD qCMAoI3ztfBMetE13TJ3ZjZ+sLaQVPrx =W0H0 -END PGP SIGNATURE- ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Davanum Srinivas :: http://davanum.wordpress.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev -- Anne Gentle annegen...@justwriteclick.com ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On Fri, Aug 30 2013, Anne Gentle wrote: I'd like to get docs closer to code all the time, but Sphinx hasn't met a few crucial requirements: translation, content reuse, PDF, and comment integration. I'd rather have repos and docs by audience than by project. To repeat, people come to docs.openstack.org for OpenStack docs. Let's make those better all the time. Oh I am not thinking about picking tools. I don't really care about what should be used. You know better than us. It's just that I know Ceilometer developers will review documentation if patches end up in openstack/ceilometer in Gerrit, thus that could allow for some part of the documentation (API, deployer guide, …) to aim for better quality and freshness. Though that system wouldn't work for documentation covering multiple projects obviously. -- Julien Danjou // Free Software hacker / independent consultant // http://julien.danjou.info signature.asc Description: PGP signature ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [Ceilometer] Documentation and patches
On 08/30/2013 09:22 AM, Julien Danjou wrote: On Fri, Aug 30 2013, Russell Bryant wrote: This is something we could get better at across all of OpenStack. I've been thinking about proposing requiring docs *somewhere* for everything that affects docs. For small stuff, it could be explaining it especially well in the commit message. For larger stuff, it could be covered on the blueprint or wiki page. I think at the least, we could provide some of the core information so that the docs team is left with figuring out where best to fit it into the existing guides, as opposed to generating the content from scratch. This directly parallels the recent thread about more testing info in blueprints. I was discussing the subject with Anne on IRC. Ceilometer doesn't have any documentation stored in any external repository (yet). My point of view is that it's better to systematically block patches not updating the documentation, than to use DocImpact and cross fingers. That clearly didn't work for us so far. Indeed. OpenStack does not have (and never will have) the kind of management that deals with these issues in a traditional engineering organization. And even in such an organization results can be mixed. All we have is gating tests and downvotes from reviewers. Of course doing things in this way would require developers to estimate more time for completion of a feature but IMO the project as a whole would benefit greatly. -David ___ OpenStack-dev mailing list OpenStack-dev@lists.openstack.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
