UP is the best tool to prevent from creating a VB6 mess

UP is the best tool to prevent from creating a VB6 mess


To prevent from VB6 messes, we still need to use XP’s techniques; however, the foundation must be UP – UP is the best tool to prevent from creating a VB6 mess

To explain the title: I have been using Java for a long time. To me, VB6 is a “friend” for correcting UP’s heaviness and creating a lightweight process. So, I have been overly nice to VB6 culture. However, the more projects I worked with VB6 teams/developers, the more I know the dark side of VB6 culture. I developed some techniques to correct VB6 problems, using UP, hence the title.

You may say I am just sitting fence between VB6 and UP, and in between there is TDD. In a sense, it is the case. However, when I am in a VB6 crowd, I would never say TDD, I will always say UP, because if you say TDD in a VB6 crowd, you will get lost every quickly: the differences are crucial (or even fatal!), but are so subtle, it is really too difficult to lead. If you use UP in a VB6 crowd, then, everything is clear. You can correct problems before they emerge, or, at least when they are just emerging.

Why the foundation must be UP? -- Because of documentation (more specifically, one-core-document documentation), use case analysis (with activity diagrams, and with mockups), and class diagrams (and state diagrams).

(a) Documentation is important: “documentation driven” is the only way to prevent chaotic mess. Note that even sometimes we get lucky and the project is a success, then, the product is in the hands of only one or two developers. That situation is not good for the team and the company.

Why one-core-document is important? -- Because passive “traceability” is not enough, we need relentless “synchronization”. That is, whenever we have changes in requirements, we need to synchronize them with design, code, test, and support. Reversely, whenever there are changes in support, test, code, and design, we must change requirements. I noticed that the reverse part is not understood by most people, they feel that requirements are from users, and therefore they cannot be changed. That is not true. Requirements must be discovered, modeled, and analyzed by analysts/developers, they are must be synchronized with other parts. The easiest way to enforce synchronization is to maintain only one core document.

(b) Use case analysis is important. Perhaps surprisingly, the key word here is “analysis”; however, “use case” defines the techniques of how to do the analysis. In the past, I emphasized using “mockups”. I still do. However, in the process of communicating with VB6 programmers, I found out that the key is “use case”, not “mockups”. In other words, if I only show them how to do the “mockups”, VB6 programmers will learn that very fast, yet will never really “get it” and therefore will create problems in practices. The problem is that they tend to believe it is “design”, so, they either get into UI details too much, or, they skip the analysis at all. Either way, they will just write a few lines of “requirements”, then, jump onto tiny details. After observing and solving the messy problems many times, now I know that I must emphasize that “requirement gathering” is not just “gathering”, it is an “analysis” process, and the technique of the “analysis” is “use case”, using mockups, and sometimes activity diagrams.

(c) Class diagrams. In the past, I emphasized that ER diagrams were fine. I still do. However, now, I emphasize class diagrams, because when you use ER diagrams, you mean to use them as a domain model, not just database schema. In other words, ER diagrams are only a convenient substitute of class diagrams. In the same line of reasoning, class diagrams are more compatible with state diagrams. However, I do want to point out that you can express states in tables also. So, really, it is more conceptual and “political” than real technical. However, conceptual and “political” thing can be very important, otherwise, you will be in VB6 mess before you know it!

The concept of requirement analysis

The concept of requirement analysis

OK, it is same things as “requirement design”, “requirement synthesis”, and “requirement research”.

In our modern world, “analysis” has some implication of “synthesis”. So, all I need to do is to emphasize that in “analysis”, we have some factors of “design”, both on business process reengineering side, and the product feature side.

Now, I finally realize DDD is actually just a rediscovery of "requirement analysis", or, just "analysis".

The concept of requirement synthesis

The concept of "requirement synthesis"

OK, it is the same thing as “requirement design”. However, a coworker of mine told me that even I point out that the “design” is “DDD” (domain driven design”, it still gives programmers excuses to jump to (mechanistic) design, which is just as bad as jumping on coding.

So, I have to avoid the word “design”.

Again, “modeling” is not a good word, because in addition to its visual implication, it also has “discovery” implication. I want strong implication of, well, design – both on the business process reengineering side, and on the product feature side.

“Synthesis” is a good word. It has strong implication of “design”, and it reminds people about “analysis” – so, it is still very close to “analysis”. As a result, it has the implication of “domain driven”.

I will begin to use this phrase, to confuse people or at least get their attention ;-)

the concept of requirement design

the concept of requirement design

Requirement discovery, requirement modeling, and requirement design (design), Requirement engineering, requirement development, requirement management, requirement validation (testing),

(a) Requirements are not just “gathered”, they are “discovered”.
(b) Further, because new business applications are part of business process reengineering, so, requirements are not just discovered, they are “designed”.
(c) Also, even only for “documenting” legacy applications, if you do not try to think about the correct way, then, you can never understand the existing incorrect ways (their outcomes are correct only because of a lot of “workarounds”). And to “think about the correct way” is “design”.

(d) Perhaps “modeling” is a better word, in the sense that it differentiates the effort from lower level “software design”.
(e) However, “modeling” has too much association of “visual modeling”.
(f) Then, if you think about it, if we use “ubiquitous domain language” in programming, it is not that necessary to differentiate the “low level” design from the high level “product design”. It is all a continuum.
(g) As a result, I intentionally use the phrase “requirement design”, just as we say “product design” and “feature design”.
(h) Without “requirement design”, there is no way to understand the requirements, and no way to find missing requirements.

How to use UML and DDD in technical writing like user manual, or requirements, specifications, design document, or test plan

How to use UML and DDD in technical writing like user manual, or requirements, specifications, design document, or test plan

You may say: the title is biased: it means that UML is just a tool for drawing pictures. My answer: correct, if only you remove “just”: it is not easy to draw intuitive pictures for all audiences across board: end users, stakeholders, managers, architects, programmers, testers, and supports. UML can do that – if you use it carefully.

The operative phrase is, “if you use it carefully”, hence the title: how to …

However, before getting into the details, I want to emphasize that except for very large projects and you have all the time, money, and people to make sure everything is synchronized, you must always insist on using one and only one core document across all phases of the life cycle of the software. It is a crucial technique. I have seen too many projects getting into deep troubles, simply because of using too many half-cooked documents and finally giving up effective and necessary documentation, and getting into a big mess.

Doing this requires developers learn to use domain concepts even in “technical” discussions, otherwise, the “design” will not be readable by “end users”, and that will break the “one core document” rule.

This was always a “theoretical headache” for me, because I used this technique for a very long time, and there was no problem in practice once you “get it”. However, to “get it”, the only way is for me to show people how to do it. It was really a pain, because I always felt that this was just a hack for “really small projects” (when in reality it can be used for large projects).

DDD (Domain Driven Design) cures my headache: if you use the ubiquitous domain language, then, (power) end users can understand most of your “technical” discussions; for the parts that they cannot understand, then, do not put it in the core document, because they are not that important after all!

The number one rule of the how-to is that do not try to use UML to replace plain English (or any natural language you prefer). The main body of the document is plain technical writing.

The reason for that is that both sides of the extremes prefer plain English than diagrams: end users and programmers. End users like diagrams only when those diagrams have sufficient text explaining them. Also, you may be surprised that programmers prefer plain English also. It is true, because higher-level language is modeled after plain English! You may say, then, who likes diagrams? Methodologists, of course! Seriously, too much diagrams is a sure sign of the immaturity of the analyst.

The core document should always split into two parts, one starts from a glossary; one starts from a list of existing applications, ordered by a typical top level work flow (note: if there are many “typical” ones, just pick one that is most “typical” and most complete). Note that if some workflows, or, some parts of some workflows, are not covered by existing (i.e. “legacy”) “applications”, then, simply assume it is a “brain-and-paper application”, and group and list those major data sheets.

Those two parts will co-evolve. We should split them apart, because they tend to evolve in different rhythms and granularity. However, it is extremely important that conceptually, those two parts belong to one document.

The glossary can be enhanced by ER diagrams. A lot of times, that is sufficient. However, we can use class diagrams instead, or, use both ER diagrams and class diagrams.

For all business applications, when you use class diagrams, just treat them as ER diagrams. DO NOT pay attention to behaviors. I know, a lot of “classic” OOAD teach you the opposite. Ignore those pedantic stuff; they have no idea about distributed computing and Service Oriented Architecture. Also, note that do not use “aggregate” (the empty arrow) in class diagram. If necessary, you can use composite (the solid arrow).

Then, what is the difference between class diagrams and ER diagrams. Not that much. In class diagram, you are closer to coding, and therefore, perhaps you can generate some code, or, more practically, you can get reverse engineering diagrams from code (but you can get ER diagrams from database also).

If it is a large project, you can use package diagrams and deployment diagrams. However, a lot of times, a simply paragraph is enough. Then, again, pictures are good for presentations, and help discussions.

Class diagrams are always necessary for the “glossary” part (that is, if you count ER diagrams as a variation of class diagrams). As a result, it is the (only) necessary UML in those technical writings. In addition, state diagram can be very helpful for some non-trivial state-oriented classes.

For the “application list” part, we do not “need” any UML diagrams. However, sequence diagrams and activity diagrams can be helpful for presentation and therefore for group discussions.

The majority of the content of the “application list” part are screen shots (or data sheets for brain-and-paper computer), using the typical flows. We need plain English to describe the screen flows, and, more importantly, the behaviors of those buttons in those screens.

Those descriptions are scenarios of “use cases”. Note that the “pure” use cases do not go with screen shots. However, without mockups, users will get confused and we will get the wrong information until too late. I have seen too many failures because of this. I am convinced that it is not whether, but when, for users to get confused and the team makes fatal mistakes. Note that “confused” also means that users are simply not interested, because: “there are no screens, they must not real, so, why bother”.

Both activity diagrams and sequence diagrams are helpful for complicated use cases. Sequence diagrams are less useful, because they tend to be too low level for users. Activity diagrams are useful for workflows. However, do not try to draw activity diagrams for every use cases, only the “interesting” ones that need discussions and attentions. In Activity diagrams, pay special attention to fork and join, and decision and merge. Always use merge explicitly. When you use sequence diagrams, you need to pay attention to the “activation bar” (or, whatever you call it) and frames (added in UML 2), for non-trivial flows – again, perhaps it is NOT a good idea to use sequence diagrams: you will find that either the workflow is too simple to use a diagram, or, the sequence diagram is too awkward for complex workflows!

Activity diagrams will be more and more popular, because more and more platforms are supporting workflows directly.

Use case diagrams are not that useful, it is simply a table of contents, with links (“includes” and “extends” etc.).

Summary: one core document for all life-cycle phases using ubiquitous domain language, split the core document into “application list/flow” and “glossary (for the ubiquitous domain language)”, use plain English; class diagram, state diagram, package diagram, deployment diagram; use case with mockups, activity diagram, sequence diagram.