Open Stack

On Sat, Oct 4, 2014 at 8:00 PM, Jay Pipes <jaypipes at 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 projects are "important" to 
>> work
>> on directly.
> 
> I don't believe that a ticket to live under the OpenStack tent should 
> come with the expectation that the Docs team is required to write 
> documentation for the project.
> 
> 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, helping them understand 
> the automated doc processes, the way that common doc infrastructure 
> works, and techniques for writing useful documentation consistent 
> with other projects.
> 
> Best,
> -jay

Amen to that, it is our responsibility as developers to do this, for 
the benefit of operators, developers, historians, ..., and users of 
openstack.

And really it isn't that hard, you just have to devote some time to do 
it (take 1/2 of a day a week to devote to doing docs for your project). 
Eventually all those 1/2 of days add up to a decent set of usable docs 
for people using your project/library/other... If we had more people 
spending 1/2 or 1/4 a day a week on improving docstrings, improving 
api/sphinx docs, improving diagrams we would IMHO be in a much better 
position with respect to on-boarding new developers and making it so 
that existing developers can understand prior architectural decisions 
(which is important for a variety of reasons, including but not limited 
to 'knowing what the reason for this code was' which can be useful 
when/if refactoring, knowing what the reason for this code was when 
adding new tests...).

IMHO we shouldn't be leaning on the docs team to do our docs, just like 
we shouldn't be leaning on the TC to say what is 'blessed' or what 
isn't; these roles should be advisory and I think they should be 
primarily spreading best practices, and leading by example (which I 
believe makes good leadership and a healthy community).

My 2 cents,

Josh

> 
> 
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev