launchpad-dev team mailing list archive

[Bjorn Tillenius <bjorn@xxxxxxxxxxxxx>]

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.  
> 
> As a new person (I won't say developer, even though I could be one) to
> LP, I'd like to learn more about the system from a high-level before I
> dive into reading code.  At the moment, I can't find any easy way to do
> this (yes, I know about Blueprints) and I can't find any LP process
> documents on the subject.
> 
> I think we should be capturing our specifications in "chunks", much
> like the Blueprint notion.  We also should be writing enough detail and
> drawing diagrams to better explain the whole system to others.  Then, I
> think we need to keep these specs in a visible location so people who
> don't know as much as we do can find them.
> 
> What do you think?

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.

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.


-- 
Björn Tillenius | https://launchpad.net/~bjornt