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 <jaypi...@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.  > > Best, > -jay > >  http://www.joinfu.com/2014/09/answering-the-existential- > question-in-openstack/ > > > _______________________________________________ > OpenStack-dev mailing list > OpenStackemail@example.com > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev >
_______________________________________________ OpenStack-dev mailing list OpenStackfirstname.lastname@example.org http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev