On Mon, Apr 15, 2013 at 7:32 AM, Rajesh Battala <rajesh.batt...@citrix.com>wrote:
> > > > -----Original Message----- > > From: Chip Childers [mailto:chip.child...@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.
