[kepler-dev] [Bug 4394] - Need to develop requirements for configuration subsystem

[bugzilla-daemon at ecoinformatics.org]

http://bugzilla.ecoinformatics.org/show_bug.cgi?id=4394





------- Comment #7 from welker4kepler at gmail.com  2009-09-28 12:50 -------
I have looked at the "requirements" and I noticed that they are fairly
low-level. In fact, they aren't all that distinguishable from implementation
details.

If you look at the label "Configuration Implementation Details" and look at the
list items under it, you can see that all of these list items there would all
fit comfortably as list items along with the items "Configuration System
Requirements."

I feel as though there is a fundamental misunderstanding here about the
difference between requirements and implementation details.

Requirements address the question of "what" but also should hint or state
explicitly the question "why." Requirements are less flexible, as these are the
things we actually want the system to accomplish. Implementation details, in
contrast, answer the question of "how." They are more flexible, in that there
are many paths to meeting the same requirements.

So, why are we starting with a very low-level design that seems to address the
question of how, before we have established the prerequisite questions of
"what" and "why"? Isn't this premature? Shouldn't our design should be driven
by our requirements, and not the other way around?

I also have looked at the design documents proposed including the class diagram
and the associated sequence diagram. I don't have any particular objections to
either of these things. (Mainly because we have not come to any agreement on
requirements.) However, I do not think they add much value at this stage. First
of all, sequence diagrams are not something that are efficient to produce for a
plain vanilla design which is fairly straightforward, as this one is. Second,
the class diagram isn't particularly useful either, especially as it consists
primarily of getters and setters and other trivial methods. It would be fairly
straightforward to develop such a simple API at implementation time.

My point here is not to criticize the hard work that went into these things. My
point is that we are focusing on the wrong things and in the wrong order. The
main questions associated with the configuration system that need to be agreed
upon are the questions of "what" and "why." The actual implementation after
that point will be somewhat time-consuming, but will also be fairly
straightforward.

Out of the documentation thus far produced, the most useful part of it by far
is the part labeled "Misc Notes." Here, we are actually getting into some
details about how the configuration will actually work and feel in practice.
That is what is actually what we should have focused on first. After we develop
requirements, whether we will actually need a design which includes class
diagrams and especially sequence diagrams is doubtful, given that the actual
system will likely be straightforward. I don't feel that these things are
optimal in terms of documentation; well-written English, an under-appreciated
skill amongst many developers, is usually a better sort of documentation.
Especially since the contents of class diagrams are easily perceived by looking
at the Javadoc, and sequence diagrams are not usually very enlightening,
especially since they are likely to drift away from the actual code. Are we
going to be updating sequence diagrams with every change in code?? As far as
guiding actual coding efforts, I do not believe that either class diagrams or
sequence diagrams are useful, especially for the experienced developers we have
here. So, if we aren't really helping the implementation process or producing
quality documentation, what exactly are we accomplishing with class diagrams
and sequence diagrams in this context? We do not have unlimited resources, so I
think we should think carefully about this question of what design documents we
really want to use (and agree on!) before proceeding with implementation. Do we
really need class diagrams that consists mostly of trivial items like getters
and setters and other trivial and obvious methods? What insights are revealed
by such a class diagram? Further, what insights does the sequence diagrams
reveal that justifies the time that went into producing it? Is the sequence
diagram supposed to be some form of documentation for future developers, and if
so are we going to invest the resources to keep the sequence diagram
synchronized with the code? If the sequence diagram is a form of documentation,
are the non-obvious insights that exist within it (and for the record, I don't
know what those insights are) better expressed in English?

Anyway, I would like to add the following items to the agenda for Friday. (1) A
discussion of the real requirements for the configuration system. (2) A
discussion of the design process we are going to use, which in my view should
not consist of the mechanical production of design artifacts but instead should
be critically focused so that we produce the design documents that are actually
most useful and effective given resource constraints.

That said, I would like to thank the people who have put in hard work in
getting the ball rolling on this.