launchpad-dev team mailing list archive

[Michael Nelson <michael.nelson@xxxxxxxxxxxxx>]

On Thu, Dec 3, 2009 at 12:15 AM, Bjorn Tillenius <bjorn@xxxxxxxxxxxxx>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.
> >
> > 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.
>


For 3.0 I tried really hard to have the PPA UI redesign process completely
open. This involved setting up a wiki page that identified the core problem,
and an outline of some initial solutions at:

https://dev.launchpad.net/VersionThreeDotO/Soyuz/PPAUI

then emailing the dev list and iteratively updating/deprecating ideas on the
wiki page based on the feedback provided by people (some people providing
their own screen shots etc.).

I also collected all the relevant input at:

https://dev.launchpad.net/VersionThreeDotO/Soyuz/PPAUI/Inputs

so that it would be possible for someone else who hasn't been a part of the
original conversation to see all the inputs (from IRC, email, etc.) in the
one spot.

Personally, the process itself was invaluable to me (in terms of getting
lots of information directly from people using PPAs on a daily basis, as
well as balancing different needs - long-term packagers versus new PPA users
with little packaging experience). On the other hand, it did take quite an
effort to keep it up to date during the process, but IMO that was worth it.

Cheers,
-Michael




>
> 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<https://launchpad.net/%7Ebjornt>
>
> _______________________________________________
> Mailing list: https://launchpad.net/~launchpad-dev<https://launchpad.net/%7Elaunchpad-dev>
> Post to     : launchpad-dev@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~launchpad-dev<https://launchpad.net/%7Elaunchpad-dev>
> More help   : https://help.launchpad.net/ListHelp
>