Open Stack

On Mon, Oct 6, 2014 at 12:52 PM, Jay Pipes <jaypipes at gmail.com> wrote:

> 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.
>

This is happening with some projects and I always encourage companies
hiring for OpenStack devs should also hire writers to keep up with those
devs.

Sometimes the tech writer is assigned only to the API docs not the operator
docs. Or all sorts of other combinations. But yes, the idea is that the
enterprise doc teams should also dedicate some of their work to upstream
patching.

And yes, I agree with the sentiment that it's pretty useless to document
any project standalone for anyone except contributor devs. Users,
operators, should write for users and operators upstream. Contrib devs
write for devs in the commuity/upstream. Also hire tech writers who are
good at advocating for particular groups and have them write for upstream
as well. Lana Brindley and I are talking about that at the Summit Monday at
17:10 http://sched.co/1qeSZbp

Nick Chase and I are working on a report about the balance between meeting
the needs of community doc contributors and finding resources for
enterprise-level deliverables. It's complicated, isn't it? It's a balancing
act.

Great discussion.
Anne


> Best,
> -jay
>
>
> _______________________________________________
> 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/18657105/attachment.html>