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
[email protected]
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
