On Sat, Oct 4, 2014 at 8:00 PM, Jay Pipes <[email protected]> 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
[email protected]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
_______________________________________________
OpenStack-dev mailing list
[email protected]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
