Hi *, On Mon, Oct 30, 2006 at 11:17:36PM -0500, Kohei Yoshida wrote: > On 10/30/06, Nikolai Pretzell <[EMAIL PROTECTED]> wrote: > >Kohei Yoshida schrieb: > >> On 10/27/06, Nikolai Pretzell <[EMAIL PROTECTED]> wrote: > >>> Kohei Yoshida schrieb: > [...] > But I wouldn't want to try spec'ing every minute detail of a feature, > and keep it in sync with the code all the time.
Nobody requests that. And this is not reasonable either. The code doesn't matter for the spec anyway. It is the User-interaction part that really matters. > And that, to me, is > what the specification project is requiring us to do (well, probably > not "all the time", but close). Specify what the code should do, not how exactly the code does it. In the quickstarter example, I would have expected that the spec would tell that a link is created in a directory that is the equivalent of the autostart folder on windows (see freedesktop-spec). I'm not interested on how the code does that, but this tiny bit of information would already explain a lot. > There are mainly two complaints I have with the current specification > project: > > 1) It asks for way too many details, especially in the UI design > section. It's not too bad if the feature involves only one > control/widget change. But once the change involves three or more > dialogs, with each dialog having an average of 7 to 8 controls, it > starts to become a real pain in the rear, [...] I disagree. Esp. when the UI is changed significantly the UI-mockups are necessary. Both for finding flaws in the proposed design as well as for documentation. I'm sure nobody expects you to do a pixel-accurate mockup, but again the user-interaction part should be clearly visualized. Making a picture of a mockup is far easier than explaining a dialog in text only. One picture tells more than a thousand words. > 2) The target audience is not very clear. Thanks to this thread, > though, now I'm beginning to see who the specification documents are > intended for (mostly for QA, right?). QA. documentation and those who want to give feedback... And of course the developers that implement the feature (if not "retrofitted") - but again here no real code design, but from a user-interaction perspective. What does the user need to do, and what is the result when a user does this or that. And don't forget the answer to "Why should OOo behave like that in the first place?" (read: User scenarios or comparison with other apps - and read as well: depends of course of the impact of the feature) In the example of the quickstart spec: I would have expected an short description what happens when the user uses KDE, what happens when the user uses a gtk based system (xfce) but not GNOME, how the user activates the feature, how the user deactivates the feature, whether it can be enabled/disabled by an admin (if so: how) If the spec would not be retrofitted, then the detailed specification part could list implementation details/proposals, such as how the quickstart works (keeping an "invisible instance", continuously catting OOo's libraries to /dev/null or whatever). > [...] > >"Responsible" does not mean he has to do the actual work. But the > >developer is the one who after all sets a task to fixed. He cannot do > >this, if the spec is not in sync, because either the implementation is > >buggy or the spec. In the latter case the QA cannot test (it verifies > >against the spec, what else?). And a feature that cannot be verified is > >not yet done. > > I don't doubt that this is how you guys do your work, and I have > nothing against it. > And if the way the stuff gets activated (i.e. the option moves to a different tabpage or something), then I'd expect the spec to be updated accordingly. (before that move is actually performed) > But doesn't an externally contributed feature come pretty much when > it's complete (or nearly so)? If so, then a spec is written after the > fact, which means the spec can be easily retrofitted to be "in sync > with the code". Doesn't matter in this case. > In this scenario, a spec cannot be used to verify the > implementation, because the implementation is done first. Well, you can still see whether what you coded actually is what you thought it would do (i.e. what you coded is what you wrote down in the spec). It is true that you miss the "find errors in the planning phase" (but again I don't think you start coding without having planned the changed first, so no gain/no loss) > You can do > the opposite, perhaps, to verify the spec against the implementation. > I did that for my first specification (natural sort), and I'll > probably do it for my second spec (solver), too. See above. Not really a problem as long as you did not just typed ahead your code.. > So, my workflow seems different from yours, which itself may be a > problem when being involved in this project. But that's how I write > my code in my free time. Still - then you know what your code does and how it should work. So how could QA know or Documentation write their stuff without knowing what is going on and where to find the feature? > >Who actually does the change (in spec or code) is an internal problem of > >the I-team and they should come to a consensus within that team, IMO. > > Ah, I-Team. Yes, definition of I-Team really sucks. Works fine as long as no UI-Changes are involved, but if not you have to find somebody from "User Experience". And although this was raised a couple of times, no easy way was pointed out (or I just didn't get it) > By the way, I usually work on my feature alone, with > occasional patches received from the ooo-build team for build fixes > etc and with occasional consultation from the Calc team and the > ooo-build team. But, for the most part, I'm usually the only guy for > my feature. :-) So you're Project lead and developer. > And I imagine this setting is not uncommon among > community hackers who contribute codes (I may be wrong though). Yes, but still you should have a seperate QA. And you probably don't write documentation (read: onlineHelp) yourself, so you need somebody fom documentation team (if applicable). And here you got your team. Just tell QA they should drag somebody from UE into the boat... > [...] ciao Christian -- NP: Helmet - Unsung --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
