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.


OpenStack-dev mailing list

Reply via email to