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 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@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

Reply via email to