Open Stack

On 10/06/2014 12:44 PM, Adam Lawson wrote:
> I personally believe that delegating the task of documentation to
> individual projects would be a huge mistake for one big reason:
> documentation exists to understand how everything works within the
> context of the solution as a whole. Very hard to do that consistently
> across all projects with the docs team entrenched in developing
> individual products.
>
> Plus, enterprise adoption of the open cloud /requires/ documentation
> that isn't an after thought. Writing code and trying to set aside some
> time to document is the sheer definition of turning documentation an
> afterthought - and no superior product has ever come from that sort of
> model.

I hear your concerns about the possibility of getting documentation that 
is either inconsistent (with respect to the other OpenStack projects) or 
not written for the right audience if we only have developer 
contributors writing documentation. You have an excellent and prescient 
point.

However, with my proposal, I was only saying that being under the 
OpenStack tent should not come with an automatic gift of resources from 
the excellent OpenStack Docs horizontal team. This process cannot scale. 
Instead, I believe it should be incumbent on the joining project to 
provide resources to work *with* the horizontal Docs team to provide 
foundational documentation for end users and operators. The Docs team 
can and should be advisors to the project contributors in how to write 
effective documentation targeted at non-developer contributors.

In addition, please see my proposal that projects applying to be in the 
OpenStack tent would have a requirement to name both a Docs liaison as 
well as a Release Management liaison. [1]

Best,
-jay

[1] 
http://www.joinfu.com/2014/09/answering-the-existential-question-in-openstack/