Tuesday, August 30, 2011

Use Cases Evolve

R1 Planned

R1 Implemented + R2 Planned

R2 Implemented + R3 Planned

R3 Implemented + Rx Planned

The use case version history, use case list, and use case text for the above can be found here in a follow-up post.

Healthy systems evolve. With each release, you add the knowledge gained from the previous release and improve the next. So naturally, your use cases will reflect that. To illustrate this, take a look at the use case diagrams for a business registration system built for the Government of Samoa. Note how they progress from release to release. Note how the implemented use cases evolve from the planned.

This registration system continues to evolve. It has 21 releases so far, with 5 major releases (include several new/updated use cases). To insure the right business functionality was built, 'worked closely with the client business experts on the use cases as each major release progressed. New use cases were discovered, some existing ones updated, and others retired. This is normal for a healthy development cycle.

Note: The meat of the use cases is the text. To me, the diagrams are a visual form of the use case list: they do a nice job of listing the use cases, their actors, and functional groupings. I'm not a big fan of / nor recommend using the fancy UML include/extends/generalization constructs; it's just too easy to venture into design and forget to concentrate on the use case text.

Friday, August 26, 2011

SQL Cookbook to the Rescue

This week was rough. We were auditing complex financial records in one of our new production databases. To do so, we had to wield some advanced SQL. I had to study-up on joins and a few other advanced techniques. How did I do it? I had a great coach: DB2 SQL Cookbook by Graeme Birchall. I found an old original PDF (here), a modern HTML fork (here), and more via Google (here).

On a previous project, some 'scary good' data mining experts and DBA's recommended this book. I've been using it ever since. Those guys were so right; this is an excellent resource for the practitioner. More, the content applies regardless of the database you use. Just adjust the syntax slightly for your target database engine and you'll be slaying queries like a pro in no time. Now here's the kicker: Graeme’s book is free to download… so no excuses, go get that data!

Favorite recipe: Multiple Counts in One Pass

13 Aug 2015 - Updated links (old ones were decommissioned).
31 Jan 2022 - Updated links again (same reason).

Monday, August 22, 2011

Black-Belt in Use Case Development

Years ago, I was an architect on a top ten world-wide IT project failure. One of my many mistakes was failing to properly collect requirements. Never again. After a lot of encouragement from a great boss and caring peers, I made a commitment to learn the best practices from accomplished veterans. First best practice on-deck: use cases. With some great teams, I mastered use case writing, led requirements efforts, and now have several successful systems in production today to show for it.

Mastering use case development is perhaps the best move I ever made on becoming a better architect.

The secret: Writing Effective Use Cases (preview) by Alistair Cockburn.

Alistair is the Use Case master. His book is probably the most valuable IT book on my bookshelf. If you've ever struggled through gathering requirements, you'll appreciate its value immediately. You wont believe how many times you jump up and exclaim, "That happened to me! That is so true!" If you're a beginner, just know that this gem contains the best practices from years of actual project experience. When you follow it, you follow in the footsteps of real architects that get projects done.

As beginners, on the first project where we used this book, the business consultants and I did nightly reading assignments as we composed the use cases. Within a month or so, we had a complete set of use cases that were fantastic, provided immediate value, and proved to be a key success factor throughout the life of the project. So with a little homework, your team can do it too.

Lesson learned: Commit yourself to mastering the practice of use case development, and DO IT.

Monday, August 8, 2011

Utilize Full Text Search

About a year ago, I released a new version of a business registration system that had one major new feature: Full Text Search (FTS). In a long series of releases, it was the most successful feature I ever added. It achieved a huge increase in effective system use and user satisfaction - it was a major win all the way around.

The system already had an outstanding search bar that could search on any combination of fields and leverage the database's powerful regular expression engine. I put a lot of work into this fancy search bar, but in practice, its power went largely unused. Frustrating!

Months later, while upgrading the infrastructure of the system, I noticed that PostgreSQL added full text search as part of its standard release. Hmmm... After digging a bit, 'discovered how it tokenizes words so that you can get better search results. For example, searching for 'industry' would match 'industry, industries, industrial' while ignoring case and punctuation. Cool.

I thought, "Hey, maybe I should add this type of search to the search bar." After a week or two of work, wow. The search results were far better (degrees of magnitude better). They were ranked. The matches were highlighted. Heck, it was like I added Google search to the system.

Here's all I had to do:
  • Choose source fields in tables to tokenize
  • Create matching tsvector fields in those same tables
    (a tsvector is a list of tokenized words)
  • Create triggers to update the tsvector fields anytime their source fields are updated
  • Adjust the searches to match against these tsvector fields
  • Tune the database's FTS engine by customizing its dictionaries to the nature of the system's data
    (i.e. additional entries to better match company names: inc = incorporated = incorporation)
Note that the terminology varies by storage engine, but the technique remains largely the same.

Lesson learned: If you're implementing a search function, utilize FTS.

4 Nov 2011 Update: See more recent post regarding using Apache Solr for enterprise search.