Adam has a problem writing to the dev list. Therefore I'm forwarding ---------- Forwarded message ---------- From: Adam Murdoch <[email protected]> Date: Thu, Sep 13, 2012 at 1:38 AM Subject: Re: [gradle-dev] Design Doc Evolution
For some reason, I can't reply to the dev list (or I can and you've all received about 30 copies of this email). Replying to the team list instead ... On 12/09/2012, at 7:42 PM, 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. 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). 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? So far, I've been moving the completed parts to a 'completed' section at the end of the document. It might be better to leave them in place and mark them as done. During the implementation process we might learn something that changes the design. 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. 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? The specs are about communicating our intention - why is this good, what we plan to do, and (usually) how will we do it? One we start writing code, the spec stops being the reference for these questions. If you want to know why, have a look at the release notes. If you want to know what, have a look at the user guide. And if you want to know how, have a look at the code. We shouldn't go back and update a spec to describe what we did. That seems pointless. For big pieces of work, they are structured into a series of smaller chunks of work that get implemented one at a time. So once each chunk is started, that section of the spec stops being the reference. In this way, big specs are really a collection of smaller story sized specs. For changes that are inspired by feedback while incubating (or later), we'd do a new spec, or add a spec to the existing big spec. -- Adam Murdoch Gradle Co-founder http://www.gradle.org VP of Engineering, Gradleware Inc. - Gradle Training, Support, Consulting http://www.gradleware.com
