Architecting with Requirements - A story from my past.

I love Software Architecture.

The essence of Software Architecture is to distill the requirements to the system. Often a developer think that a requirement is absolute: "Our software must do this. To the letter." However, when you dig a little deeper, most requirements are quite flexible. Remember that a requirement comes from a customer, and very often ends up being written by the customer based on his interpretation of your system.

Vivo, a Brazilian operator, had a set of requirements for Nokia that specified how the UI of their mobile phone should look and behave when in idle. For Nokia, these requirements were very hard to implement as written, years or man-hours work. The requirements were sent to Nokia in form of a large document. The document was interpreted by a Customer Representative that 'understood' Vivo's requirements. He entered them into a database where various teams could comment and respond to them. Eventually, they reached a Project Manager that decided to implement them, after which point they went to a Software Lead, who made sure his team got them and coded them.

By the time a developer got these requirements, it was too late. Un-winding the history was impossible, and frequently Nokia spent insane amounts of time not only managing this, but trying to figure out what Vivo really meant in the first place.

As one of my tasks while working as the Chief Software Architect for Nokia (CDMA products), I was sent to Vivo to discuss these requirements. The development teams were stuck, the work was overwhelming, the product would be delayed.

I met with Vivo's lead UI/Marketing person, Raquel, who was responsible for writing the original requirements. As we started discussing, I began asking questions along the lines of "So why do you want this? What is your purpose of asking for that?" Each time Raquel would answer honestly, describing what Vivo was hopnig to ultimately achieve with the feature (Drive revenue, make it easier for users to find and buy content, etc). When we came to the requirements that were hard for us to do, I suggested alternative ways of doing them. Often just a little tweak, but enough that Nokia could easily implement it, instead of making major changes. And Raquel accepted. She was thrilled that we could do it all of a sudden. The phone could be done on time.

In this scenario, what were the essential issues?

1. The requirements were written with pre-conceived knowledge of our UI
2. The requirements lost their original context when processed through Nokia's DB
3. The core reason for each requirement was 'lost in translation'.

My point is... As a Software Architect, sometimes your main purpose is to understand WHY requirements are what they are. Use that to suggest alternative solutions that still fullfill the need, and always... always ask for purpose!

Surveys

Finally we're getting some help in the S&M Department (No, it's Sales and Marketing). A very experienced friend of a friend, Bob, has agreed to help us start understanding our customers, and tap into their view of LiveProject.

This has also prompted me to due some major e-mail list shuffles, which I must admit is tough when you have had 85,000+ people sign up. E-mails just don't fit so well in Excel anymore.

So after much ado about nothing, I finally had to give in and write a bit of a 'tool' for MailChimp. Their new API guy, Jesse, has been helping me with their .NET Beta library, which has saved me oodles of time.

Now, we are surveying all our customers, and learning a heck of a lot. Should any one of you read this (highly unlikely given my 3 hits per day on this blog or so), then THANKS !

Getting to Page 1 on Google

"Content is King" they say. So, in the spirit of content, I decided to add our entire help-page system (Which is already made up of *.htm pages) to our website.

We would increase our relevant content quite significantly, and allow customer to browser our help pages online. A win-win proposition.

In reality though, this proved to be more work than what I initially estimated. Our help pages are built using the HTML Help Workshop, and my first task was to clean each individual page of all header and body tags. Each page would simply have to start with a h1 tag.

• This format still works in the HELP file, which is great !
  
• This allows us to embed the help files directly into ASPX pages with a simple wrapper and include statement:

Now, any change to a help file can be updated on our web page by just adding the file directly to our web directory.

Now, the problem was that IIS was configured to open *.htm as web pages. So, a quick reconfigure later, and the include works (and we have no other htm pages anyway).

My last problem is that each *.htm file includes links to other *.htm files. But each htm file is embedded in an ASPX page, so the links don't work.

Using a URL rewriter, I simply setup a rule to re-direct any requests for *.htm files to the corresponding *.aspx page. Nice!! I love URL re-writing!!

Google even managed to index the pages, which is great, BUT google fails miserably when reading the title tag. For some reason each title becomes an "unknown page", most likely due to the redirect.

While finding the ultimate destination correctly, google seems to 'use' the 'missing page' it get's from the URL redirect header (Or something to that effect), so now I have to find and resolve that issue.

Getting to Page 1 on Google

After many month of optimizing our website (Best damn project collaboration tool around), I have finally gotten a good solid idea of how to optimize for google. Let me say, it's surprisingly easy, and bound to get harder. As sites starts competing, the keyword-shuffle can begin.

So, Lesson 1 in my own story of getting to page 1 on google (and altavista, live, ask.com, etc)

1. Use the same keyword on the title, header 1, bold in body text, and lightly strewn around the pages. Don't overdo it (Like I have on some pages). If you can, make sure the keyword is part of your domain name. If that's impossible, then make it part of your page name (Like Great Cookies):

BEST: www.greatcookies.com/Fantastic.html
GOOD: www.bambionice.com/GreatCookies.html

Remember to use image ALT and TITLE tags, they are great for keywords, as are the TITLE tag of your links.

URL Rewriting and Google Website Optimizer

I've begun discovering the power of URL rewriting. As our KaDonk website is growing furiously, URL rewriting is the only good method of fixing old pages that have been removed.

This becomes particularly true after having run several Google Website Optimizer tests. The Google website optimizer are great, but when using A/B pages, let's say on registration.aspx, you inevitably end up with registration1.aspx, registration2.aspx, etc... These pages are just temporary for using while the experiments are running.

Once the experiment ends though, users may have links to these pages, and search engines may have indexed them.

So I installed a freeware URL rewriter, and now all I have to do is redirect the temporary pages to the main one after each experiment. Simple, and clean.

Another benefit I recently discovered was when we added our entire library of help files to our website. These are the same pages that are included in our F1 Help inside LiveProject. Internally, they all reference eacher using *.htm links. But our pages are in ASP.NET, so references would basicallyshow the raw files instead of my encapsulator .aspx files.

URL rewriting to the rescue. Each reference to a .htm file is automatically redirected to an .aspx file of the correct name. Literally with one line of configuration all the links in our embedded help files works.

It looks something like this:



May I add this is insanely cool !!

Redirecting domain.com to www.domain.com through global.asax

OK this was a tricky one to solve, redirecting kadonk.com to www.kadonk.com using ASP.NET in C#. The solution came from lots of browsing, and many sources, and looks like this in global.asax (replace 'domain' with your own domain of course):

void Application_BeginRequest(object sender, EventArgs e)
{

// Don't do nothing while in test mode !
if (!Request.Url.Host.Equals("localhost")
&& !Request.Url.Host.ToString().Contains("www.domain.com")
&& Request.Url.Host.ToString().Contains("domain.com"))
{
string Result = string.Concat(
"http://",
Request.Url.Authority.Replace("domain.com", "www.domain.com"),
HttpContext.Current.Response.ApplyAppPathModifier(Request.Path),
Request.Url.Query);

HttpContext.Current.Response.Redirect(Result, true);
}
}

This will redirect kadonk.com to www.kadonk.com, but not any other domains we have, and it won't touch localhost (which may be funky). It will preserve Session variables and query strings, and should generally be nice and safe. You will note that I hardcoded "http://". I will fix that later to retain the protocol, but in any case I am using Matt Sollars GREAT WebpageSecurity package for SSL redirects!