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