launchpad-dev team mailing list archive

[Brian Fromme <brian.fromme@xxxxxxxxxxxxx>]

On Wednesday 02 December 2009 04:15:28 pm Bjorn Tillenius wrote:
> On Wed, Dec 02, 2009 at 12:00:33PM -0700, Brian Fromme wrote:
> > Hi,
> > 
> > It's my opinion that we should have a more visible model for Launchpad
> > design specifications.  
> 
> We have to be a bit careful here. We've tried this many times in the
> past, and they have failed. The thing is that people design things,
> implement them, and then change it. The design might even change during
> implementation, since you find out more about the problem then. It's
> actually a high cost of changing the design document when you change the
> system, since it's a context switch. This leads to stale documentation
> that is out of date, and confuses people more than it helps.
> 
> The only way I see something like this working is if the documents live
> in the source tree, and are doctests so that it's natural (and you're
> forced to, since it will start to fail) to change the specification when
> doing changes to the system. Actually, it doesn't even have to be
> doctests. It should be documentation with tests. It would probably be
> possible to have a normal unittest test, exctract the comments, and
> produce a suitable document.

For the lower-level descriptions of work, I agree that this is difficult and perhaps too costly.  We still do need a way to describe an enhancement (or other piece of work) to others before we start implementing it, though.  Right?

> We also have to come up with a good level of details. IMHO, these should
> be very high level, so that they won't need to be updated that often.
> The more detail you include, the harder it will be to write, and the
> harder it will be to write, the lower the quality will be. I think we've
> had enough experience in this field to know that it's better to have
> this very lightweight. If the process isn't lightweight it will fail.
> That's why I think that diagrams are pretty much out of the question,
> except for very simple ascii ones.

This is my intention.  I think we should focus on the high-level descriptions that give someone a basic understanding of the parts of Launchpad and where to find those parts in code.  This will be mostly useful to new developers.  These designs should remain more static than lower levels, or if they do change, it seems worth updating the high-level design.  Maybe we should be calling this an "architectural" description.

 Brian