The True Technical Architect

“Architecture“… what a grand word. Grand words with grand meanings emit a mysterious aura of sophistication and elegance. I won’t deny it. I, myself, fell in love with that word.

The Architect of “The Matrix” is pictured as a calm old fellow with the wisdom of Buddha and the profoundness of Shakespeare. That’s how Hollywood (read: people) perceives software architects… ahem, well, that’s not so far from the truth.

Many times, I see “Technical Architect” on business cards and in resumes. But what does that title or role really mean?

When there is ambiguity, I go back to the basics for an answer. That’s why, in a humble attempt to make things clear, I try in the following paragraphs to meticulously define the concept of “Architecture” and then move on to sketch a rough drawing of the true architect like I picture him or her.

Architecture… of What?

That’s the first wise question one should ask. I like to poke “Architects” and ask them… what do you architect? what kinds of decisions do you make? I either get back a blank stare, or another question plus some pseudo-random output: “what do you mean? I just do it. High-level stuff. I pick technologies.”

Well, we – developers and software engineers – build systems. But let me be more precise. We actually develop Applications. We might also integrate our Applications with other Applications into a System of Applications (think your web app, DBMS, FTP, Email, and BlaBla servers for example). These applications we build and integrate do not run in vacuum. They run, possibly, on top of other applications (think containers) that run over platforms (think Java) which run on operating systems which, in turn, run on hardware. Applications may also need to communicate over networks.

The union of all the above mentioned elements represents an IT Solution – a wild beast, and a complete answer to your customer’s business need or problem.

Great. Now, let’s define “Architecture” In the context of IT solutions. Architecture is essentially “Design” — only a high-level form of it. To design something is to…

…plan something for a specific role or purpose or effect; “This room is not designed for work”

The True Architect

So basically, to call myself an “Architect”, I should have had planned – at least once – either an entire IT solution or part of it for a specific intended role or purpose or effect. If that sounds easy, think again.

The very first purpose of any kind of IT solution is to be functionally correct and functionally complete; i.e. the solution (including all custom-developed applications) completely and correctly fulfills functional requirements, plain and simple.

But that’s just the beginning. All the “neat” tricks and conquered challenges behind great architectures (such as Google’s) were direct results of ruthless non-functional requirements and constraints – Performance, Scalability, Security, and Availability to name a few. Fulfilling those requirements is therefore an essential part of overall IT solution architecture. How to do that under different project constraints (available budget/time/ resources, imposed technologies/platforms/operating systems, etc.) is the name of the game.

That’s on the solution level. On the Application level, amongst the most important non-functional requirements are Maintainability, Extensibility, and Configurability. Architectural patterns such as Model-View-Controller (MVC) for example became so popular because they facilitate maintenance, extensibility, and configurability of otherwise spaghetti-coded web apps.

Another important aspect is that technologies bring along their limitations and performance characteristics. That’s why choosing technologies that most fit the purpose of the application/solution is one of the most fundamental and far-reaching decisions in IT solutions development. Technology is always a means to an end.

Bottom line

So anybody who did application or solution architecture once can mark himself as an architect. However, a true architect who earns my respect is one who has lots of real-world experience in meeting non-functional requirements in ruthless production environments. A true architect is someone who has developed a rich tool box of principles, patterns, and anti-patterns of solution and application architecture.

Boost Your Productivity Using Apache Tapestry

If you are like me, you really don’t have time to waste with frameworks that suffer from favoring “elegance of design over everything else”.. take the old EJB model as an infamous example.

Personally, all what I care about is finding new ways to improve productivity. Nowadays, I prefer frameworks and APIs that are designed for simplicity of use in the first place. You invest some time and effort, and gain back generous increases in productivity.

If you’re into Java-based web applications, you probably know how challenging it is to develop the UI Layer of the application — while keeping View code clean (readable) and neatly separated from back-end code.

That’s why a number of months ago I decided to go on the hunt for the ultimate UI framework — if it ever existed. I pictured a framework where complexity of handling UI events and moving data back-and-forth between Model and View is hidden from the developer, such as with desktop applications.

I enumerated a number of frameworks from java-source.net. I did not consider some excellent technologies such as AdobeFlex and another framework called ZK (watch out for that one) just because you do not write the interface in HTML or any close markup, but rather in completely different proprietary language.

I also ignored frameworks that do not have an online demo. Presence of an online demo is the least thing framework owners should offer to their prospective users… lack of an online demo gives me negative vibes about the health of a UI technology.

I ended-up looking at a couple of JSF implementations, Apache Tapestry, and Apache Wicket based across several dimensions:

• Learning Curve
• Maturity (which reflects on other traits such as reliability, security, and performance)
• Programming Model
• AJAX Support

The following are the results of my quick research. This is not an extensive research, with anything but concrete results. I was in a rush (as always!). I just brushed over the surface, with high reliance on first impressions and short test drives. Use the results with caution!

I easily ruled out JSF. I got the impression that it was plagued with the same “elegance of design over everything else” virus that used to plague Java specs (the situation is getting better now). As usual, JSF needs tedious XML configuration. Plus, web pages are written in JSF markup which is a turn-off to me. Yes, I don’t care that JSF is a specification.

There was a number of open-source implementations: Apache MyFaces and IceFaces. Only IceFaces seemed to be mature and impressive enough anyway. The documentation of IceFaces was far from complete or accurate, and it seemed to me that in addition to the learning curve of JSF, there will be another trickier learning curve mounted over it… to learn the “secrets” and internals of IceFaces (that was with version 1.5 as I recall, now I’m seeing a version 1.7 so perhaps things have changed).

What really clicked with me were Apache Tapestry and Apache Wicket. There is some similarity between them; they are both “component-based” frameworks that map parts of the UI in the HTML pages 1-to-1 to Classes and Objects on the server. Component-based frameworks are far more easier to deal with than JSPs and other frameworks that expose the cycle of request/response handling (such as the old Struts). Tapestry hides the request/response handling cycle pretty neatly.

So, I gave Tapestry a try. Although the documentation is not the best that they could offer, it is very extensive. The quick-start guides delivered a really quick start. I actually was able to write a simple application in a couple of hours, and boy, I was impressed with Tapestry’s potential. We’re talking super-productivity here once you get over the initial (relatively shallow) learning curve. Add to that the following great advantages:

• You write your Web Pages in pure HTML (now XHTML with Tapestry 5)… Tapestry’s markup is elegantly hidden within HTML markup.
• Moving data from your business logic to the web UI and back is as easy as populating and extracting data from POJOs using setters and getters.
• Built-in AJAX support, DOJO and Scriptaculous are integrated.
• It is easy to build your own components and extend the framework.
• Page navigation is easy and intuitive… no need for lengthy XML files as in JSF.
• Persisting data into a Session is a matter of calling a “set” method on an annotated POJO field.
• Tapestry adopts the convention-over-configuration philosophy. No piles of XML configuration files, just put the jars in your Lib directory, add a couple of entries in your Web.xml, and everything just works.

After I experienced Tapestry, I was quite impressed and decided to skip Wicket and get started with Tapestry immediately. Tapestry and Wicket are more or less similar, only Tapestry is more mature. However, Tapestry has its flaws as well, ones that I recognized when I got up close and personal with the framework. So, if you decide to use Tapestry, be ready to live with the following issues:

• First, you have to decide which Tapestry version to use. 4.x and 5.x are completely different and there is no backward compatibility. 5.x has been in “beta” stage for a long time now, but as far as my experience goes, it is stable. 5.x is far more simple than version 4.x due to its streamlined design and the use of Annotations.
• The documentation on the website is extensive and sufficient… but as soon as you start meeting more complex scenarios, things start to get a little darker… and in some cases, you might need to do the occasional dive into the internals of the framework to understand how things work.
• Tapestry 4.x is not satisfactory on the performance side due to the design of its request/response handling cycle. 5.x is much better on the performance side.
• For some reason, the releases of Tapestry are few and far in between. I don’t know why. That framework has lots of potential.
• The only book on Tapestry covers 5.x and seems to be significantly outdated. Many of the book’s examples are obsolete and do not work with the latest release of 5.x. So that brings us back to rely on online documentation.

Bottom line: Tapestry is a great framework that boosts productivity, a framework that has been elegantly designed and written for the sole purpose of making your life easier. The cons of Tapestry can be lived with, and the framework’s clean design makes it easier to understand its internals. You’ll enjoy working with Tapestry. Kudos to the Tapestry Project team.

5 Keys to Great Requirements Documents

Critical activities in any software project heavily rely on the presence of high-quality up-to-date business requirements.

Architects base the architecture and design of a system on requirements. QA draw their test plans from requirements. Developers start working off documented requirements… that how it should be at least.

So bottom line, you will have to record requirements in one form or another. This applies even if you’re an agile process supporter who believes in light documentation. The following tips can and should be adapted to suite your documentation practices.

Prototype First

Frankly, I don’t know how anyone could NOT do this step. Prototyping really simplifies requirements documentation. The prototype usually becomes the most important part of requirements, for the following reasons:

• It minimizes the inevitable risks of requirements change, and gives your requirements much wanted stability. Users start to be enlightened and understand what they really want as soon as they have some working prototype to interact and play with.
• Screenshots (an output of basically any prototype) are essential parts of Use Cases or User Stories; they reduce the amount of writing required to the minimum… you just include the screenshots and reference them.

Prototypes can be as simple as drawings and sketches on white paper, more complex and interactive like “paper prototypes” or can be done using a specialized prototyping tool.

But the prototype is only the beginning of the story. While prototyping, you should start planning how you will document the requirements represented by the prototype.

The next step is to…

Know and Honor Your Audience

In all documentation I’ve seen and examined, this is one of the most ignored fundamental principles. You have to understand who you are writing for, and then write to give them what they expect.

First and foremost, you write for your customer. So pay them due respect and:

• Understand your customer’s lingo and use it.
• Write in the customer’s preferred language, if possible.
• Organize requirements in the document by priority – the most important to customer first.
• Use simple diagrams and illustrations extensively – customers really dig pictures way over long boring text.

Don’t forget the rest of your audience in the project team. Understand what they expect and take their input into consideration.

Never Start with a Blank Page

Templates exist out there for a reason. One of the greatest opportunities in documentation writing is to re-use the knowledge and experience gleaned by other people in the form of templates.

Starting with a template can give you a great jump start. But almost always, any template needs customization to fit your needs. Strip a couple of sections, add a few, and change the name of some others until you are satisfied.

The point of customization is to create a simple and concise document. You have to question the presence of each and every section in your document. Ask yourself questions such as: is that section really relevant? Who of my audience will find it interesting and why?

Great templates that I’ve used myself include those of the Rational Unified Process (RUP).. you can also take a look at the templates of the open-source ReadySET project.

Pick a Style and Be Consistent

“Consistent” here must be in everything – from your writing style of Use Cases and your use of terminology to the use of diagrams. Consistency makes it easy for anyone to quickly scan the documentation for a piece of information… not to mention being a fundamental trait of any professional document.

Be Prepared For Change

You must have heard it thousands of times: the most certain thing about requirements is that they do change. If you do not keep up with the changes, the requirements document loses its value and fails its purpose.

That’s why you have to be careful while picking your prototyping technique. Is it easy to update your prototype?

But what should you do when requirements change? Do you go back and change the requirements document? Yes and no.

Yes, if the requirement item (use case or feature description) has not yet been implemented. You go update your prototype and your requirements document.

The answer, however, is No when you have already implemented these requirements. At that point, the system itself manifests the requirements. So you go update the system. But that will leave the requirements document outdated, won’t it?

In my opinion, this is fine – as long as these changes are tracked in an issue tracking system. That way, you can spare your effort and “batch update” the requirements document if you ever needed or wanted to.

Review and Refine with Your Customer

After you’ve produced something, don’t just email it to your customer and expect them to review it or even read it carefully. That ain’t happening. Except in the most motivated of customers, the correct way to do it is to go in person and review and refine it with them.

Oh, and on the way, arm yourself with the patience of an ant — you’ll need it.

Hello, World!

Courtesy of oskay, Flickr

This is my first official post to this online space. I’ve started writing here with one clear mission in mind: to reach out and be an agent of positive change. I’ll share with you, dear reader, the experiences, the mistakes, and the success stories.. all in the hope that it will help you somehow, someday.

This online space shall be focused on telling the occasional war stories of an IT Solutions Engineer living and working in Egypt.

As in every social first encounter, I’ll start with a quick intro about myself. I’m Moataz Anany, an IT Professional living and working in Egypt. I’ve acquired my B.Sc. from Cairo University, Faculty of Computer Engineering in 2004. Since then, I’ve worked in a couple of start-ups then in a number of recognized places, last of which is IBM, in the Global Business Services (GBS) subdivision.

I’ve spent most of my professional life as a devoted software engineer doing development under Linux; particularly using Java EE technologies.

Finally, I wish to see you here often and share with you your thoughts and opinions on upcoming writings!