Building a project documentation framework

Properly maintained documentation is of crucial importance to any project team and project manager regardless of project type and methodology used. Agile methodologies of today mostly advocate little to no documentation which might seem as a good idea, but in general it is a bad idea because sooner or later you will have to explain why has something been done this or that way, who order and authorized the implementation of functionality x in this specific way, the developers and tester will need to validate that requirements have been met and so on.

So when you get a supreme guru justice league developer or project manger telling you that he can complete a project without documentation don’t believe for a second that it’s a good idea. While the statement it self might be true and one can complete a project without proper documentation you can be sure that there is a whole world of pain down the road for you.

Currently I’m managing a mid-large enterprise system, that has several maintenance and upgrade contracts running concurrently which are handled by different development teams on different platforms and technologies and it is crucial for all of our teams that they have current and up-to date documentation on the system. Still we can’t afford to waste valuable man days on mountains of papers and documents so we had to choose  a proper amount of documentation which had to cover our basic needs

• Easy to write and maintain
• Clear and unambiguous
• Understandable to technical and non-technical personnel
• Easy to relate and transform to other documents

We started of with the basics of the Agile methodologies and the user story format and built our requirements document around it. The current requirements document corresponds to an Epic consisting of a scenario list like “Editing an xx”, “Searching for xx”, “Calculating xx” which consist of a story list table detailing all of the user stories required. The document in it self is a simple decomposition of the user actions which exibits the following traits

• focuses discussion on user actions and process
  
• client stakeholders can easily relate to it
• it contains sufficient information for the development team
• it does not predetermine any part of the actual implementation

Of course the document is always signed and confirmed by all parties project manager, client representative and development team  representative.

So we happily started to write our requirements documents and after a while when we got bug reports we saw that we could not identify how the current version of the system should behave since it consisted of user stories implemented over user stories over user stories etc. Then came the decision that we should have a document that will be updated as we implement user stories in the system will describe the current state of the system.

To satisfy that need we used the Use case form as a basis for functional description of the system. The use case document is updated during sprints by the business analysts as user stories are implemented consistently representing the current system functionality. This document covers needs different form the requirements document such as:

• description of current system functionality
• detailed description of required steps to complete an action or process
• detailed description of UI
• detailed description of implemented business rules
• detailed description of the implementation of user stories

By developing the use cases from the requirements document we inadvertently managed to kill three flies with one blow. We quickly realized that the use case document since it details implementation and user actions, can easily in mater of an hour or two be transformed into test cases and user manuals. Then from the test cases it was a mater of a couple of hours to build automated UI test which dramatically increased the testing coverage and quality while reducing the load on our testing team.

With this we saw the ultimate benefit of keeping a decent level of documentation of our system and that is improving the overall quality with reducing costs and time-pressure development teams. The second benefit of this documentation system is that our team members can now focus on their primary job with a clear goal ahead and a clear condition of done.

The business analysts develop User stories with the stakeholders, architects review and design the system development teams concentrate on developing the best software based on User stories, the testing team can develop test cases based on the use cases and automated test based on the test cases, the support team has detailed specifications to review, test and categorize bugs, thus completing the circle and easing the job all round at the expense of investing a little bit of time in developing some documentation which comes back big time as a reward in the form of clarity of functionality, faster development and most important of all quality.

Using TransactionScope for handling transactions

Implementing transactions from C#/VB code today might seam easier than ever before, but the path to easier and effective transaction handling has many traps on the way. Microsoft made the life of developers seemingly easier by implementing the TransactionScope class in the .net framework 2.0. I say seemingly easier because you sometimes might find your self baffled by the way your code will behave.

The TransactionScope class uses MS Distributed Transaction Coordinator to manage transactions, so before you start using the TransactionScope, make sure you have DTC running on the Web and Database server and that you have granted enough security permission for the DTC to be able to communicate on thoes machines.

So to get started with TransactionScope, here is a simple code example that seams perfectly OK.

using(TransactionScope outerScope = new TransactionScope())
{
    // Execute query 1

    using(TransactionScope innerScope = new TransactionScope())
    {
        try
        {
            // Execute query 2
        }
        catch (Exception)
        {
        }

        innerScope.Complete();
    }

    outerScope.Complete();
}

Now if query 2 which is inside of the try/catch block, rasies an error you will catch the exception in the try/catch block and handle it, but here is a supprise the application will throw an ObjectDisposedException on line 15 when you try to complete the transaction. This is because the DTC has already caught the exception and although you have handled it, the TransactionScope objects where already disposed by the .Net code and the transaction has been rolled back. Notice that I have said “objects” this is because both of the TransactionScope object have been disposed as they are a part of the same transaction. This is just one example where you might seam surprised that the code is not behaving as you would expect.

The TransactionScope implements something that is referred to as an “Ambient transaction”. This is the transaction in which all database queries are executed. When I say all queries I mean all queries that are executed between the creation of the TransactionScope object and the calling of the Complete() method, including all method calls and their method calls and so on, that are executed between those two lines. That means that you don’t need to handle the transaction in every method that participates in the transaction unless you want to.

You can control the manner in which a method participates in a transaction quite easily. Here is a piece of code to demonstrate:

using(TransactionScope outerScope = new TransactionScope())
{
    // Execute query 1

    using(TransactionScope innerScope =
          new TransactionScope(TransactionScopeOption.Required))
    {
        // Execute query 2
        innerScope.Complete();
    }

    using (TransactionScope innerScope =
           new TransactionScope(TransactionScopeOption.RequiresNew))
    {
        // Execute query 3
        innerScope.Complete();
    }

    using (TransactionScope innerScope =
           new TransactionScope(TransactionScopeOption.Suppress))
    {
        // Execute query 4
        innerScope.Complete();
    }

    outerScope.Complete();
}

This demonstrates the use of the TransactionScopeOption Enumeration to control the way some piece of code will participate in a transaction. The enumeration consist of three options Required, RequiresNew and Suppress. The default options for the TransactionScope constructor is “Required” which states that an ambient transaction is required for this operations, if non exists the transaction will be created. The options “Suppress” states thata the this TransactionScope will not participate in the transaction and therefore all database queries are executed without a transaction. The option of “RequiresNew” states that a new ambient transaction will allways be created and become the root transaction.

There are further options that can be modified when using the TransactionScope class by using a different constructor TransactionScope Constructor (TransactionScopeOption, TransactionOptions) that takes the TransactionOptions struct as a parameter here is an code example.

TransactionOptions options = new TransactionOptions();
options.Timeout = TimeSpan.FromMinutes(1);
options.IsolationLevel = IsolationLevel.Serializable;

using(TransactionScope scope =
      new TransactionScope(TransactionScopeOption.Required, options))
{
    scope.Complete();
}

The TransactionOptions struct has 2 properties Timeout and IsolationLevel. The first is self explanatory the timeout prior to completition of the transaction. The second one is more important, I would say my self crucial to effective handling of transactions. The IsolationLevel Enumeration consist of several levels of isolation: Serializable, RepeatableRead, ReadCommitted, ReadUncommitted, Snapshot, Chaos and Unspecified. With the “Serializable” isolation level being the strictest and “ReadUncommitted” begin the least strict form of isolation.

Serializable means that all transactions occur in a completely isolated fashion; i.e., as if all transactions in the system had executed serially, one after the other. That means no other transaction can be run until the one running is completed. This type of isolation should be used very carefully since it can cause massive timeouts etc. if used with long lasting transactions.

RepeatableRead is a step down from Serializable isolation level, where multiple transaction can run at the same time, but all data read during the transaction can not be modified (exclusive row/page locks) and volatile data cannot be read.

ReadCommitted is a further step down in isolation where the transaction allows for reading and modifying of data that has been used in a select statement, but volatile data cannot be read or changed by other queries.

ReadUncommitted is the least strict isolation level where the transactions can see uncommitted changes performed by other transactions, allowing for dirty reads.

More on isolation levels on Wikipedia.

That sums up the basic use of the TransactionScope class with more to come 🙂

Top Gear

That one show about speed, cars and octanes that we all love to watch.

I watched a lot of different shows about cars and related stuff, but one show is the cream of the crop, the kingpin, the leader of the pack. The show is running on BBC now for about two decades set the standard for all others to try to follow, many of them did and have succeeded to a certain degree, but they could only do so much.

I found a nice torrent, and I’m downloading it as I am writing this. The torrent is the seasons of the show as I can figure it from 2002 to 2006. Of course I have already downloaded the latest 2007 shows, and watched them all already. You can see most of the shows on YouTube, if you have not already seen them. There are a lot of clips and most of them contain whole episodes.

Here are two that I especially like, episodes that capture the brilliance of this show.

The race to the North pole, Toyota Hilux vs sled, the episode where they go head to head with the Aston Martin Vantage V8, BMW M6 and Porsche 911 Carrera S and my favorite The destruction of Toyota Hilux.

The core of the show today are the three presenters, that think up the shows and the test, which lets be honest are not that scientific, but they are so fun. The thing that makes this show stand out is the witty and classy British humor and the pure passion of the presenters for what they are doing and they don’t see the making of the show as a job, rather as a fun time. That is what first attracted me to the show, and I believe that this a must for making a good show.

Blogged with Flock

23

Yesterday I watched the latest movie with Jim Carey. The title is simply 23. It’s probably the only movie in which Carey’s character is normal so to say. The character is a guy obsessed by the number 23, the movie it self is a thriller, with a dose of paranormal. Now I would say that in the movie there are 2 stories, the first being the story of a killing of college student, for which a professor was convicted, and which was in fact killed by Carey, and the other story being the story about the number 23.

Now there is a certain mith around the number 23, that the number 23 appears is all around us and certain events are marked with 23. Now for some 23 is a sign for a good event, but the majority believe 23 to be a bad thing. Why let me give you a couple of examples.

1. The human genes have 46 chromosomes, 23 from the father, 23 from the mother.
2. 23 seconds is the average time that takes for the blood to recirculate.
3. 9/11 2001, add the number up 9+1+2+1 = 23
4. Hiroshima, the bomb was dropped at 8:15 = 23
5. Charles Darwin’s Origin of Species was published in 1859 – 1+8+5+9 = 23
6. Although the Old Testament is unspecific, it is widely held that Adam and Eve had 23 daughters.
7. The 23rd verse of the first chapter of Genesis brings the act of creation to a close.
8. The 23rd chapter of the book of Genesis deals entirely with death, namely that of Abraham’s wife, Sarah.
9. The most famous and most quoted of the Psalms is number 23: “The Lord is my shepherd; I shall not want. He maketh me to lie down in green pastures: He leadeth me beside the still waters.”
10. Passage 23:23 “What hath God wrought”
11. The bible has 22 chapters.
12. Julius Caesar was stabbed 23 times
13. The knights Templar had 23 grand masters.
14. “W” is the 23rd letter of the Latin alphabet. It has two points down and three points up. White supremacists use 23 to represent “W” as a mark of racial superiority.
15. The earths spins in cone at an angle of 23,5 degreese -> 23 + .2 + .3
16. The procesion of that spin is 23500 years
17. The cancer of Capricorn / crab 23,5 degrees
18. April 19th as in 4-19… 4 + 19 = 23. April 19 is the date the Battle of Lexington, Waco, and the Oklahoma City Bombing.
19. The number of joints in the human arm is 23
20. The human life cycle is 23 days.

and so on. There is a huge list here http://afgen.com/numbr23b.html.

Now why is that so interesting, it’s just a number repeating it self. OK now divide 2 by 3, and you get .6666666 and so on to infinity. The believers in this theory believe that the 23 is a hidden signature of the devil him self.

So lets examine this examples more carefully. Now I would say that we should rule out any and all of the occuraces of the number 23 where there are humanly designed measurements involved. Like degrees, time, dates, alphabets, none of those are acceptable, because if you apply a different measuring unit the number 23 disappears.

Like 9/11 2001 in our calendar, but if you use the julian calendar the date is 8/29 2001 which does not add up to 23 in any way, or you could use Hebrew 6/23 5761 or islamic 6/22 1422, by which we can conclude that in that one particular calendar system the numbers and to 23, but in the others they have nothing to do with 23.

Lets use 23500 year period that takes the earth to complete its procession. Here it gets even worse, the period was once longer, and has a consistent decay rate, and once again the earth will be spining on a vertical axis. But if you again convert from our time measurement to let’s say the mayan (which had a more accurate calendar than our own Gregorian), the numbers are not even close.

OK now the letter W, letter W is the 23 letter of the Latin alphabet. Not so, it is the 23 letter only in English based alphabets. In the Croatian, and the rest of the Slavic based alphabets there is no letter W, as is no in Asian alphabets or African or South American, and if there was it would not be in the 23 place.

By now you should be aware of the need to filter out the occurances of the number 23 in anything that relates to some human measurement. Because if you measure something to be 23 miles long, in the metric system it is 39 km long. The only thing left is the are those numbering occurances like the 23 chromosomes from the mother and father each to child.

With the filtering out off all of those occurances, you would get a number of occurances of the 23 in some normal statistical pattern as the rest of the numbers.

The only thing now left interesting in the number 23 is that it is:
1. the first prime number with consecutive digits
2. the first prime number with both digits being prime numbers
3. the first prime number where the digits add up to a prime number (5)
4. primes 2, 3, and 5 are the first three prime number of our the decimal system.
5. that 2 is the only even prime number
6. that 3 is the first odd prime number
7. 2/3 is .666666

Blog recyling

While i was trying to think up a new name for my blog, not the title. but the domain name, I found a lot of the names where taken. I was prepared for that since I know how many people have their blogs on this service, and I figured that the good ones have already been taken.

But I was suprised that when I checked some of those domains, example. simplyclever.blogspot.com that I found that that blog was inactive since 2004, or more or less 3 years now. The blog has only one post on it, and that is it. As far as I am concerned I believe that the blogger service should recycle those blogs, and release the domain name for others to use.Now if and when the user logs in back to his account, which is highly doubtful, after 3 years of inactivity, the  user has to pick a new domain name for his blog, since his old domain name, for the reason of inactivity was recycled. This should also be an interest of the blogger service, since I belive the intent of those running the service is to have as much active bloggers, and not empty blogs, that no body touched for over 3 years.

That would also improve the happiness of those opening new blogs, since they would know that they have a shot at the domain name they like. Rather then knowing that the domain name is used by nothing.

Start of a slow begining

I am quite of a casual gamer, you know that type that always complains and always wants more and more of features etc. I understand game developers have a hard time of developing games and adjusting them to please as much gamers as possible. Since I am a software developer my self, and I always have to bend over for my clients, whose count fortunately is not in the millions rather just a dozen of those super smart “managers”, you could say that i have it easier then the game developers.

I have often thought about writing my own game, to correct all that stuff that i found lacking in the games i played. I found often that the games had a good start, but at a certain point it seams like the development stopped, and the features that could have been implemented have not been.

Until now I did not think that one man, without no previous knowledge about game development, directx, graphics and etc. could do, I am a back end, enterprise solution developer, so drawing is not something that I am good at. But now after a saw a few demonstrations by Microsoft, on WinDays, TechEd and community conferences XNA Studio could solve a lot of my problems.

So off to install XNA. First to download the installer, some 80 MB download free from microsoft, and lets try it. But then i find out, I dont have a habit of reading those readmes and so on, that you need Visual Studio Express C# SP1 installed. So I figure this has to be an install bug, since I have Visual Studio Team System SP1 installed on my laptop. But <span style=”font-weight: bold;”>no </span>Microsoft decided that for now it would only support the Express version of Visual Studio for use with XNA Studio. So i download the C# Express version, and install it the same with SP1. Next i find out that the Express version does not support my favorite add in ReShaper, which i find as an essential tool for any serious development. But luckily Microsoft is considering running XNA Studio on other version of VS in the future.

So to recap, to start with XNA you need:
1. Visual Studio Express C# (no exception, there is no hack to run XNA on other versions of VS)
2. Visual Studio Express SP1
3. XNA Studio 1.0 refresh

The OS on my laptop is Vista, and XNA Game Studio does not by its spec support Vista, but fearless as I am, I did it anyway, so far I did not have any problems.

Loaded the SpaceWar example and started to try to figure it out 🙂 keep you posted