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 _______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
