Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-07 Thread Christopher Yeoh
On Mon, 06 Oct 2014 11:24:30 +0200 Julien Danjou jul...@danjou.info wrote: On Sun, Oct 05 2014, Joshua Harlow wrote: I agree. I think we should have documentation be part of our policy to accept patches, just as we do with e.g. unit testing. Forcing people to write documentation along the

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Julien Danjou
On Sun, Oct 05 2014, Joshua Harlow wrote: IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be able to play an advisory role for new projects,

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Flavio Percoco
On 10/06/2014 11:24 AM, Julien Danjou wrote: On Sun, Oct 05 2014, Joshua Harlow wrote: IMHO, it should be up to the project itself to provide the resources to work *under the guidance* of the Docs team to write developer, end user and operator documentation. The Docs team members should be

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Kenichi Oomichi
-Original Message- From: Chris Friesen [mailto:chris.frie...@windriver.com] Sent: Saturday, October 04, 2014 1:27 PM To: openstack-dev@lists.openstack.org Subject: Re: [openstack-dev] [all][docs][tc] How to scale Documentation On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Thierry Carrez
Jay Pipes wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Zane Bitter
On 06/10/14 06:07, Thierry Carrez wrote: Jay Pipes wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Adam Lawson
I personally believe that delegating the task of documentation to individual projects would be a huge mistake for one big reason: documentation exists to understand how everything works within the context of the solution as a whole. Very hard to do that consistently across all projects with the

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Jay Pipes
On 10/06/2014 12:44 PM, Adam Lawson wrote: I personally believe that delegating the task of documentation to individual projects would be a huge mistake for one big reason: documentation exists to understand how everything works within the context of the solution as a whole. Very hard to do that

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Adam Lawson
I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle Openstack's current list of integrated programs, offloading the work to individual projects exchanges one challenge

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Jay Pipes
On 10/06/2014 01:39 PM, Adam Lawson wrote: I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle Openstack's current list of integrated programs, offloading the work to

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Chris Friesen
On 10/06/2014 11:39 AM, Adam Lawson wrote: I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle Openstack's current list of integrated programs, offloading the work to

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Anne Gentle
On Mon, Oct 6, 2014 at 12:52 PM, Jay Pipes jaypi...@gmail.com wrote: On 10/06/2014 01:39 PM, Adam Lawson wrote: I like your suggestion about the Docs team being advisors. I would submit however (my opinion here) that whether or not there are enough resources on the Doc'n team to handle

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-05 Thread Maish Saidel-Keesing
On 05/10/2014 06:00, Jay Pipes wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-05 Thread Davanum Srinivas
One tool that ASF infra folks came up with was the Apache CMS, this helps the individual projects contribute to maintaining their documentation. They used Markdown format. Since we use DocBook, we could use a converter like pandoc (http://johnmacfarlane.net/pandoc/) later in the life cycle to use

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Sean Dague
On 10/04/2014 12:26 AM, Chris Friesen wrote: On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better page-based design and navigation for

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Anne Gentle
On Fri, Oct 3, 2014 at 11:26 PM, Chris Friesen chris.frie...@windriver.com wrote: On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Jay Pipes
On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which projects are important to work on directly. I don't believe that a ticket to

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Joshua Harlow
On Sat, Oct 4, 2014 at 8:00 PM, Jay Pipes jaypi...@gmail.com wrote: On 10/03/2014 09:18 PM, Zane Bitter wrote: The prospect of a much larger tent with many more projects in OpenStack-proper shines a spotlight on the scalability of the Docs team, and in particular how they decide which

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-03 Thread Anne Gentle
On Fri, Oct 3, 2014 at 8:18 PM, Zane Bitter zbit...@redhat.com wrote: Amidst all the discussion about layers and tents there has been this lurking issue about Docs and their need to prioritise work that we haven't really done a deep dive on yet. I'd like to start that discussion by

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-03 Thread Chris Friesen
On 10/03/2014 07:50 PM, Anne Gentle wrote: Here's my current thinking and plan of attack on multiple fronts. Oh, that analogy is so militaristic, I'd revise more peacefully but ... time. :) 1. We need better page-based design and navigation for many of our docs. I'm working with the Foundation