cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jessica Tomechak <jessica.tomec...@gmail.com>
Subject Re: [DOCS] Documentation focused committers, and review processes
Date Mon, 15 Apr 2013 19:31:28 GMT
On Mon, Apr 15, 2013 at 7:32 AM, Rajesh Battala
<rajesh.battala@citrix.com>wrote:

>
>
> > -----Original Message-----
> > From: Chip Childers [mailto:chip.childers@sungard.com]
> > Sent: Monday, April 15, 2013 7:47 PM
> > To: dev@cloudstack.apache.org
> > Subject: Re: [DOCS] Documentation focused committers, and review
> processes
> >
> > On Sun, Apr 14, 2013 at 06:05:48PM -0500, Joe Brockmeier wrote:
> > > On Sun, Apr 14, 2013, at 02:19 AM, Radhika Puthiyetath wrote:
> > > > Any penalties for people who BLOCK documentation development ?
> > >
> > > Are there rewards for the folks who aren't blocking documentation
> > > development? It's not like we can dock their volunteer pay. ;-)
> > >
> > > In all seriousness - I'm sure that it's frustrating to do the work and
> > > wait on feedback that is slow in coming. But every project suffers
> > > from more work than hands to do it. I don't think we should be looking
> > > to penalize or shame anybody, we just need to find ways to help people
> > > do their work more efficiently.
> > >
> > > We *could* revert features where the developer has not reviewed
> > > documentation, but who does that help? Assuming a feature is complete
> > > and isn't buggy, is it better for the user not to have a feature
> > > because someone didn't have enough time to review docs? Probably not.
> > >
> > > In this case, I think Chip's proposal is the right one: docs folks
> > > should do the docs to the best of their ability, commit, and raise the
> > > new docs to the attention of the developer(s) specifically responsible
> > > for the feature and the dev@ list in general. (And perhaps even the
> > > user@ list.)
>

The suggestion to get the users list involved is a very good one.


> >
> > +1 to what Joe said.  Do the best you can with the information you have,
> > and harass developers until you get a response.
>

I'm sure this is exactly what is already being done. I believe the problem
Radhika raises is that sometimes, there is no response from the developers,
no matter how many requests are made or in what imaginative fasion they are
issued to try to get attention.


> >
> > -chip
>
> +1 for joe and chip


Please pardon my ignorance, but I have a couple of questions. When
developers commit code to the repo, it's required to go through a testing
phase before it's included in a release, is that correct? Or do we put out
some code that's half-baked, and if so, does it have maybe a comment at the
top like "Work in progress"?

I'm just trying to get at whether the expectations for code and docs are
the same, and even whether they ought to be the same, or not. I am fine
with Chip's and Joe's suggestions that the doc committers go ahead and
commit whatever documentation we have to the repo, even as we're still
waiting for an accuracy review (analogous to the testing phase for
code).That's what I already do anyhow.

I'm just wondering how we want to handle the case where review never
happens, or not in time for a scheduled release. I agree with Joe that
there's no point reverting an entire feature just because its docs were not
reviewed, but I'd be in favor of either pulling out the docs or at least
stamping them with some kind of caveat like "Preliminary draft, accuracy
not guaranteed." What do folks think about that?

Jessica T.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message