On Wed, Sep 12, 2012 at 12:01 PM, Luke Daley <[email protected]>wrote:
> > On 12/09/2012, at 10:42 AM, Hans Dockter wrote: > > > I'm thinking about how to improve the transparency of our planning and > the accuracy of our planning message. > > > I think the bulk of the real planning is happening now in the design > docs. Which is exciting. > > Except the review feedback loop, at least for me there's a lot going on in > email around the doc. Not necessarily a bad thing, but it's not open and > transparent. No idea what to do about this. > I think it is fine to have the bulk of the initial discussion on the dev list. Once we would have it somehow in the forum (more on this in another email) I think both channels will be used. Let's see how this will work out. I think it will be fine. > > > This is something that works, gets updated, etc... I see the design docs > as the master data for any planning transparency and also for our public > roadmap (which is stale and far from up to date at the moment). > > Makes sense. > > > Before I share my thought on the roadmap I would like to discuss the > evolution of the design docs. Very often a design doc contains many stories > which we will implements step by step. Some ideas in the design docs will > never be implemented. There is always more you can do after all. > > > > - Do we want to mark in the design docs what has already been > implemented? > > - Do we want to remove the implemented parts from the design doc? > > I think they should only be forward looking and describe unsolved things. > If something is implemented/solved, it doesn't need to be mentioned unless > it's relevant to something else being discussed in the doc. > > > During the implementation process we might learn something that changes > the design. > > We can't in practice write the design doc, then go and implement. That's > waterfall and it doesn't work. This is only waterfall if you stick to the design doc. I guess there are different phases for how much the design doc drives the development. We might reach a phase were we don't care about updating the design docs. Don't know. > I only say this to point out that it will be the norm that things will > diverge during implementation, so we do need strategies for dealing with this. > > After the implementation the correct spec for a feature should live in > the documentation. Would we care at this point to update the design docs? > Or do we consider them as transient document where we kick out what has > been implemented. > > No, design docs are only forward looking. They should get retired > somewhere. > What about partially implemented design docs? This will be the norm I would say. > > > Also during the incubation phase we might change the design based on the > feedback we are getting. Would we always go back to the design doc to > update? > > I wouldn't say always, but for anything of size yes. Design docs do not > need to explain how something is implemented, they just facilitate the > discussion necessary to do just enough up front design. I don't really want > to have to keep them completely accurate for any other reason. > Absolutely. Hans > > > I kind of like the idea that the current design docs only contain what > we are planning to do. That way they are also very suitable to be used as a > roadmap (more on this later). > > Same. > > -- > Luke Daley > Principal Engineer, Gradleware > http://gradleware.com > > > --------------------------------------------------------------------- > To unsubscribe from this list, please visit: > > http://xircles.codehaus.org/manage_email > > >
