Open Stack

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

This is a matter of making reviewers aware of this issue. As much as we
want to make it official, there's probably not a good/easy way to
enforce it besides asking reviewers to be nitpicky on these things.

By requesting docs on reviews, we'll encourage people to write docs
right away next time.

Cheers,
Flavio


-- 
@flaper87
Flavio Percoco