Open Stack

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, 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).

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 patch will help writing
better code, having a better understanding of what the patch does for
reviewers, etc…

And will obviously benefit to users and operators.

-- 
Julien Danjou
;; Free Software hacker
;; http://julien.danjou.info
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 818 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141006/31db3c4b/attachment.pgp>