Open Stack

On 10/06/2014 01:39 PM, Adam Lawson wrote:
> 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.

I guess I wasn't clear in my suggestion. I am proposing that the joining 
project be responsible for bringing resources to the table -- and not 
developer resources, but tech writer resources. I think developers can 
and should work with the Docs team, but I also think that projects 
should hire or source tech writers themselves to handle the end user and 
operator documentation.

Best,
-jay