Open Stack

I like your suggestion about the Docs team being advisors. I would submit
however (my opinion here) that whether or not there are enough resources on
the Doc'n team to handle Openstack's current list of integrated programs,
offloading the work to individual projects exchanges one challenge
(scalability) with another problem (quality). Using that approach, doc bugs
will get triaged with the other project bugs and potentially distracts
developers from doing what they do best - writing and fixing code. And what
happens when you only have time to fix a feature or work on documentation?
Focus on features and performance/stability are going to win. Every time.
And they should because that what the program teams should be focused on.
That means we start down the road heavy on code because developers can't do
everything, making them light on documentation forcing a catch-up process
to ensure which requires a special team to preserve momentum, bringing us
back to where we are now. I've been there before. And I'm sure others have
as well.

I've always been a big proponent of exploiting strengths vs building on
weaknesses and I'm going to step out on a limb here and speak to strengths
which may get me into hot water with some so I want to apologize in
advance. ; )

If a team of developers is tasked to produce all of the documentation for
enterprise consumers, I hate to say it like this but you'll end up with
highly-targeted documentation that makes sense to a developer and possibly
low-level engineers. That level of detail is probably best served in
README, wikis and mailing lists. It isn't effective as a user's manual.
Even with coaching, we'd be coaching folks to do things they aren't good
at. Same goes for a solution architect writing documentation the other way
around - you end up with documentation that speaks so broad, it fails to
make the impact that a targeted/focused approach is needed by the
engineering consumers.

While documentation produced by each individual project makes a special
kind of impact, it must be one spoke - not the entire wheel. I love the
idea of advisors and they should provide the first draft but I also believe
a dedicated team is needed to ensure quality doesn't suffer.


*Adam Lawson*

AQORN, Inc.
427 North Tatnall Street
Ste. 58461
Wilmington, Delaware 19801-2230
Toll-free: (844) 4-AQORN-NOW ext. 101
International: +1 302-387-4660
Direct: +1 916-246-2072


On Mon, Oct 6, 2014 at 9:59 AM, Jay Pipes <jaypipes at gmail.com> wrote:

> 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 at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20141006/7ade2796/attachment.html>