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/

_______________________________________________
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Reply via email to