Last week, I visited the Øredev conference. I had a gread time and since this is the forth time I attend the conference, I can see how much it has grown from the first year in 2005. Back at this first conference in 2005 I presented myself together with Magnus on the topic of AJAX which was a bit of a hype at the time. I don't know why I did not even blog about this then but sometimes I am a lazy blog writer... :( Anyways, seeing all these great speaker it does trigger an enthusiasm to get back into the game. We'll see, maybe next year I'll make a shot at present something at some conference. Certainly Øredev would be my first choice. If they would let me in again...

This year the conference was for a whole week. Two days with workshops and courses and three days with regular conference sessions. I visited the 3 days only this time. Although I probably did not manage to always pick the topic that suited me the best from those available, I think I still got a little something out of everything.

The topic of the conference was "Share Knowledge" and I think this is certainly true and a well chosen phrase. But most of all, for me, it is about getting the inspiration to dig into new fields of interest. Most, if not all speakers are very dedicated about their own topics of interest and I believe all of them spend a share amount of their own spare time to become as knowledgeable as they are within theses areas. This is the essence of passion I think. That you volunteer to walk the extra mile in order to stay on top of things and in control. Naturally this brings with a certain amount of enthusiasm in the air that is easy to grasp and feel. So, to me, the importance of this visit boils down to this important sentence: 

It becomes easier to remember that it is fun and rewarding to stay passionate about your work after a visit to Øredev.

This is a simple statement but in essence it often means that you will pick up a work related book after work or sit down in front of the computer once again after an already finished 8 hour session during the regular work day. An easy thing to say, but less simple to achieve. But if you are passionate about something it definitly becomes a lot easier. Essentially:

Passion is what drives us to become better at what we do.

Another nice thing about Øredev is that it there are many cross-discipline tracks. So it is easy to slip into the Java track, or the Testing track for instance when you feel the curiousity of a topic. There were 12 different tracks to choose from this year so I think it was quite easy to find something interesting somewhere. Naturally, there were sessions that collided making me bring out the dice, but video recordings of sessions are coming up I hear. So this parapgrah basically brings on the next important punch liner:

Øredev makes it possible to think a bit more outside the box you tend to place yourself in after weeks and weeks of regular work.

I find it a bit hard to retell which sessions I attended and what I thought about them. Basically since it would be a book writing that I never would finish. But I do say that the absolute highlight for me this conference was to see and hear Robert C. Martin speak. His book Agile Software Development, Principles, Patterns and Practices has meant a lot to me as a software developer. It has completely revised the way I think about code and the importance of making a good design. There were a lot of quite famous people on the conference so I'll just skip the remaining name dropping here and instead urge you to view the excellent program selector (as already linked to above).

Oh, one more thing definitely worth mentioning:  Øredev did support this year builing schools in Africa via UNICEF which I think was an honorable thing to do. I bought a brick at the conference and I encourage you to do the same. It is probably never too late to be a hero.  

Last but not least:
Mucho thanks to the Øredev team that pulled this togheter once again this year! Looking forward to next years conference already!

This morning I woke up to a real nightmare. Yesterday I had set the alarm on my mobile phone to wake me up at 6.30 in the morning as usual. I knew when doing this that I probably would suffer a bit waking up since I went to bed way too late. But what the heck, it is only sleep, my last train of thought went before going to sleep. Oh, did I pay for this a couple of hours later!

Since my girlfriend wasn't getting up as early as me I had been particularly careful to set the alarm to use an increasing volume. Also I turned off the phone battery vibrator since this tends to make the whole room vibrate when the alarm rings, which even wakes up our cat Disa who usually sleeps at my feet.

Before I go on and tell you about my nightmarish wake up, I'll tell you about a previous experience with another brand from this particular mobile phone manufacturer. That mobile phone screamed out with a terrible melody whenever the battery was getting low. In most cases, this is probably a good thing since you really want to make sure this never happens. But with this particular mobile phone, it was not configurable to turn this feature off. So naturally, the alarm woke us up in the middle of the night on a number of occasions.

Eventually I managed to learn that phones' user pattern to take the battery out before going to sleep. Or even better, plug in the electric charger... Anyways, I think most people would value sleep over the mobile phone not running out of battery.

So, back to my devilish wake-up this morning. At 6.30 this morning the mobile phone alarm started ringing at a low volume as should be. Unfortunately the alarm went off during the wrong time of my sleep cycle so I was really dead tired with most of my brain neurons still sound asleep. I also woke up finding that my left arm was missing. I could not find it anywhere.

As the sound of the alarm screamed louder and louder, I slowly realised that my arm was gone because I could not move it. It was completely lame. I did not feel it anymore.

This can happen if you sleep with the arm in a weird position for a long time. It will wake up again and becoming fully functional after a couple of minutes of free dangling time. So I actually did not panic. Yet.

So that leaves me with one arm and a tenth of my normal brain power to turn off the phone. Piece of cake you would think?

A regular alarm clock usually has one big “turn-off-alarm button” that is easy to find. This morning I realized that there is a reason for this. In my delirious dreamy state, I started pushing all the buttons all at once on the phone with my functional hand. But nothing happened. Instead the alarm started to ring louder and louder. With a steady arising panic I begun to realize that the alarm would never ever again be turned off. I would have to live the rest of my days with this noise ringing louder and louder in my ears.

So I fumbled on in my quest to turn the damn thing off rushing out of the room, stumbling over poor Disa who for a second managed to scream louder than the phone. Perhaps if I poured water on top? (on phone, not cat!) The electronics probably doesn't like this so that would probably work.

Fortunately, my brain power was slowly booting up again so I never fulfilled my idea. Instead my one hand remembered the old trick and after lots of struggling (one hand!), I managed to pull the plug out of the sound by removing the battery.

Phew! Silence! Finally!

But the screaming alarm was still reverberating in my head with anguishing anxiety. And I knew that my girlfriend was probably lying in her bed cursing me and only me for this! Well I curse the phone in turn!

Ok, so having woken up a bit and sitting here at breakfast with my beloved cop of coffee, again being able to hold it with two hands, I think I realized what went so terribly wrong this morning. Firstly, I now grasp that I sometimes never will learn how to turn the alarm off the ordinary way. Especially not so with one tenth of my brain power and one arm at my disposal. Secondly, for some reason the phone key lock is sometimes not lifted when the alarm goes off. This is clearly a software bug since normally, one only has to puch any button to turn the alarm off. Devastating bug I would say... And if it is not a bug and if there is a logical explanation to it, well even worse. If I find this to be the case, I might even reveal what brand of mobile phone it is in this blog post.

Some thoughts on the future of mobile phones

Mobile phone companies have started to talk a lot lately about turning the mobile phone into a generic all-in-one toolkit; kind of like a Swiss army knife. Keys, credit cards, you name it. I would love for this to happen. But I also would love the phone software developers to think in turns of how these devices are actually used in each scenario. Why is there a big button on the alarm clock and how can this be simulated better and always work on a mobile phone?

These type of questions, I think is always extra important to ask for product manufacturers. And particularly so when they are to support a new functionality that it originally was not designed to support. As in simulating an alarm clock when you are in fact a mobile phone.

Naturally, looking back at this morning I laugh about my desperate attempts to turn the alarm off. But I also think that I never will buy a mobile phone from this particular manufactorer again. But then again. Perhaps I will. I am usually less cranky after I have finished my morning cop of coffee.

This blog post is part of a series that start here.

I have already descrived what the Running Mate is and why I would like to build such a thing. Now, it’s time to get my hands a bit dirty with the mathematical theory that’s needed for this. I would not say that it is an advanced mathematics, but it is definitly a fun applicability since it is really easy to see and understand the purpose and need for the mathematic formulas.

So here’s my 10 km run again. Let us focus on small area of this run: the square that the red arrow points at:

If we enlarge this square area, it would look something like this:

As you can see, I’ve painted some blue stars on the map and high-lighted the road with a black line. The blue stars signify the GPS points that my running mate is picking up with the help of the satellite(s). I don’t know how often these coordinates actually come, but naturally, I will not be able to get the exact track of my run. By drawing a line between the coordinates we will se how the running path looks like according to the PGS system. Here is another image high lighting the coordinates with their straight lines between them in an X-Y graph instead:

Calculating the distance between these stars in this graph is simply a matter of utilizing the Pythagorean Theorem. I honestly think that no matter how rusty your math knowledge becomes, this formula will forever stick in your head:

z² = x²+y²,

z is evidently being the sought distance between two of the stars in my graph. So in order to withdraw the distance between the second and the third coordinate, the formula becomes:

z² = (x₃-x₂)²+(y₃-y₂)²

Calculating all distances between all coordinates on the map gives us the total distance which is exactly what shapelink.com did for me when I utilised their service to draw my run on a map. Basically, I gave them the coordinates by clicking on the map and they drew the lines in between these coordinates and calculated the total distance of the run.

But we are still not at where I want to be: getting the current time comparison of each spot to a previous run. And this is where the fun begins.

The difficult part here would be to compare different coordinates from different races with each other. Naturally, the coordinates will not be on the exact same place as the previous coordinate. This image will illustrate this:

Here I have high-lighted a second race coordinate with red stars. As you can see I did not run the exact same spots as I did the last time I ran the race. The deviation shown is most likely larger than what would be in reality considering that the track I run on is quite narrow. But nevertheless, I obviously have to take this into account when comparing the coordinates.

Naturally each coordinate also has an associated timestamp. As I see it, finding the coordinates that are closest to each other in order to calculate the difference between the two timestamps can be done in at least two different ways. Let us start with the easiest one.

Algorithm: Finding the closest coordinate

So, as this image shows, we have to calculate the distance (d1, d2, and d3) for each red coordinate to all blue coordinate and pick the one that is the closest to the red coordinate. The needed calculation is basically just a matter of using the Pythagorean Theorem again a number of times, so it is a piece of cake really.  

In the example in this image, the d3 distance is obviosly the shortest one so this coorrelating blue coordinate is selected as the one to compare against the red coordinate. The difference in timestamp between these two coordinates would give you the desired result for the Running Mate application. If we don't need  a more accuracy result, this is where we would stop.

However, of course we want more accuracy, so let us move on to the more interesting algorithm.

This blog post is part of a series of blog post that starts here.

Well, to be honest, it has been available all since this Monday before the Swenugpresentation. But I just added some missing files too so now it actually compiles too... Sorry about this if someone chose to download the code right after the presentation.

As perviously stated in this blog post series, I initiated the creation of the Running Mate mostly because I needed a demo application for a performance talk. It served its purpose well I think, and I think I can make use of this applications in upcoming presentations. However, being a demo application, it is far from complete in functionality:

• There is no PDA based version of this code built yet. I.e. the device that tracks and sends the GPS ticks as you run to the server. Obviously without this, there is no purpose of the Running Mate. So I hope that I or someone else will have the time to build this eventually.
  
• There is no real Graphical User Interface built yet. I built a test load client for simulating the load and I also built a windows client application for inserting the test data into the database which both are available. But the real GUI is not built yet. I have some ideas for this and hopefully someone will help out with this GUI eventually since GUI is not my cop of tea...

As for all the source code it is available here: http://www.codeplex.com/runningmate. It is published under the GNU GPL v2 license model.  You can quite easily use Subversion (TuroiseSvn client) URL at https://runningmate.svn.codeplex.com/svn or the TFS Server URL at https://tfs05.codeplex.com.

I am usnig SVN myself and unfortunately, the throughput is very low. I suspect Microsoft is actually to blame here since Codeplex is a very popular open source repository these days. Microsoft don't seem to have scaled codeplex to meet the demand. If it does not improve or if I see it is a problem I might move to another availble code repository. We'll see.

The current file folder structure in the repository looke like this:

Although this most likely will change in the future, the idea is that a working, non-demo version of the code will be available in parallell with the DemoVersion folder. Eventually..

In the VisualStudio folder, all the C# 3.0 code is placed. I am using Visual Studio.NET 2008. Currently, I am running MySql as the data persistance provider, but I might make more options available too. After all, MySql requires a MySql server to be installed in some way or another (there are quick ways to install it) so it is a bit too much of a hassle to get the application up and running if you are not using MySql. The DB folder has everything you need here though for the application script wise, but please let me know if something is missing.

Hmm, that's it for know I think. I'll back on the topic of design and architecture in an upcoming blog post.  

Ok, so this is my third blog post today. Gotta be a record for me I think.

On Tuesday I will be presenting on the topic of performance optimization at Swenug in Göteborg. This last year I have been working quite a lot with this focus at Admeta. The topic of this talk is: 1 billion web request - response time 50 milliseconds. This is actually not a lie since we have these types of requirements at Admeta. One billion request is quite a high number so I do understand if there is a mild hesitation if it really can be true. But asynchronous requests from multiple high load pressure web sites can stimulate this type of requirements, trust me.

I believe the presentation will be approximately 2 hours, but there will be room for some discussions. I've been at a number of Swenug presentations by now here in Göteborg and I think the atmosphere is very relaxed and nice. I hope for the same nice athmosphere on Tuesday with lots of interesting questions and discussions. So this is what I planed and prepared for my presentation:

1. Load testing process and demonstration

Load testing is of vital importance in order to understand how the load pressure will affect your web site. Scaling with more machines is not always something that you can do hastily if the need arises and it sure does cost a lot of money to do it. So it's good to know a little of what you application could behave in production before you launch it. In this part I will go through the load testing procedure, what to look out for, what data to collect, and give various other hints based upon my experience in the area.

2. Performance Profiling with the Running Mate application

For profiling och optimising, I will demo with a new hobby application that I just recently built: The Running Mate. The special thing about this application is that I have built the domain very loosely coupled with regards to the application layer making it possible to switch the domain layer at runtime. I am basically providing these different types of implementations:

a) The Super Hack: this was the running mate application as easy as I could possibly implement it. Not much design work. But fast?

b) The Overkill Design: This application is a bit overkill since the domain model is interchangeable in runtime. I would say that in most cases, this is not how you would normally decouple the domain layer since the need for it often just isn't there. However, it is very useful if you would like to profile performance with regards to different types of domain model implementations. The architecture pattern is that one of the Domain Driven Design (as described by Eric Evans) which gives the system a very nice Separation of Concern I think. One of the provided domain models is using a traditional Data Access Layer implemented in DDD repositories. The other provided domain model is using the Mindscape LightSpeed O/R mapper which we have used at Admeta for quite some time. As you can see in the link it is providing a bunch of nice features and it is very nicely DDD oriented.

So, I think there is enough substance here for a two hour session with discussion. All code demonstrated during the evening will be provided at CodePlex at http://www.codeplex.com/runningmate very soon.

     This blog post is part of a series that starts here.

Well, beautiful and peaceful isn’t all, is it? The current condition and health situation surely makes running a lot more enjoyable. And in order to get in fit which makes running a great sensation, you have to run faster and push yourself a bit.  So this blog post is basically about finding this motivation with something called the Running Mate.

In order to motivate myself to run a bit faster, I clock the time it takes to run the distance. But unfortunately I seem to be stuck at about 55 minutes for 10 km run which is a bit too long time I think... I know. There are various good ways to improve the time: run more often, vary with shorter distances etc. If lowering the time would have been of really strong importance to me, these ways of doing would probably suffice for me. But as it, my level of interest makes me look in the direction of technical tools to help me out…                          

My problem when I run is probably motivation and focus at the running process itself. I let my mind wonder and I think of everything except keeping the correct pace. Running is great for problem solving by the way. Anyway, the clock does not give me this feedback since I have no idea of what time I am supposed to have when I am looking at the clock during the run. Naturally, this can be solved by having a number of part times at specific distances. And I do, but I don’t really want to keep track of too many of these part times since it disturbs my thoughts on other things. I would like to be able to know instantly, at the time of interest, what my pace is compared with a previous run at that exact spot of the run.

So the answer is obvious: The running mate application. It has been possible for quite some time now to buy a GPS equipped watch with this type of applications. The main idea is that it should be possible to run against yourself, i.e. being able to compare your current running time against a previous time you have had in a previous run at each and every spot of the run.

So I could have gone ahead and bought this GPS device. But something has stopped me so far. Of course it would be cool and exciting to fabricate this tool myself with the help of a mobile phone and a GPS device. Not that I know if I will ever get around constructing the whole thing, but I intend to build something in code and blog about it. I do this partly because it is a fun thing to do, but also since I think this application could be the basis for future examples both on the blog as for presentation I do.

So next blog post, coming up soon I hope, will be about the mathematical geometry needed complete such an application. Fun stuff I think.

For quite some time now, I’ve been thinking of the design of a so-called Running Mate application. I decided that it was time to implement it and the trigger that set me of was to have a fun example to use at a performance tuning presentation. So beneath is what I have in mind as blog topics although it can change somewhat as I go ahead:

1. The Running Mate – What is it and why?
   This is a personal touched blog post with the background story as to why on earth I think the Running Mate application is a nice thing. Off course, this blog post also lets you know what the application is actually doing
   
2. The Running Mate – Code available at Codeplex
   Source code available and some words about what is provided and what is not provided in the repository as well as some file structure information.
   
3. The Running Mate – The geometry calculations
   In order to implement this application some interesting geometric calculation is needed. This blog describes these calculations.
   
4. The Running Mate – The Super Hack implementation
   Sometimes I start off by doing a rather quick and dirty implementation of the application and then refactor my way into a more nice design. I didn't actually do this for this one, but I needed super hack implememntation for my presentation. So this is breif presentation of a quick and dirty implementation.
   
5. The Running Mate – The Domain Driven Design approach
   In this blog post I transform the application into a design that is closer to a Domain Driven Design.
   
6. The Running Mate – The O/R Mapper Repository
   The repositories built in the previous blog post uses a classical database access layer wrapped in repositories with inline (ad hoc) SQL. Here’s an alternative approach with the MindScape LightSpeed O/R mapper.
   
7. The Running Mate – The loosely coupled Domain Layer
   Most O/R mappers integrate into the Domain Model rather tightly and make it a bit more difficult to switch from one O/R mapper to another one. This is a bit strange since O/R mappers themselves make the choice of underlying database very flexible. In this blog post I describe how you can decouple a domain model from the application so that you can have several different versions of domain layers that the application can utilize. The loosely coupled domain model is not always that useful in reality, but it is a nice experiment.   

I may change the topic names slightly as I go ahead and write about them, but I hope you can live with this. There are actually many more blog posts that I can write based on this application. For instance I would like to write some more about the LightSpeed O/R mapper and how you can wrap the basic CRUD stuff to make these methods really easy to access with a simple API. Also, there is a lot of stuff on performance tuning this application that I would like to write about eventually. But I better not promise too many blog topics in advance since you never know what lies round the corner.

So. Basically, I am back in the blogosphere for another round.

In a previous blog post, I covered the following topics:

·         Published, not stored which basically allows for more people to read the document.

·         Refactoring structure allowing for documentation to stay agile and up to date with a current content and structure.

·         No special roles, instead accountability for taken actions!

·         WYSIWYG vs. wiki syntax basically stressing that simple editing markup is good enough for most types of documentation.

In this post I will instead dig into the following two topics:

·         Local feedback which allows for history of decisions to be associated to the source of the information.

·         High cohesion and low coupling is a well known programming principle. I think this principle can be applied to documentation as well which is better supported with wikis than in file based documents.

We sure do communicate with each other a lot at our job. This is mostly done in a synchronous way with verbal communication. Most often agile methodologies favor verbal communication over written communication since it is considered as the most effective way.

However, there are other ways of communication which are of an asynchronous nature. Such communication allows us to write information or questions to other people and do other things while waiting for the response to come back.

Asynchronous communication also allows for us to take the time to formulate a good text that correctly describes the important part of the message. Sometimes this is a great strength over verbal communication since in an intense moment we do tend to talk past each other, not understanding what the other person is trying to say.  Of course it can also be a weakness since we don't get an immediate feedback of what we are stating. But this is a completely different blog topic which I probably will write eventually.

However, an example of such asynchronous communication is of course mail, which probably still is our most commonly used communication tool at companies. Yet another example is some kind of chat messenger like MSN Messenger or ICQ which also is of an asynchronous nature. In fact you can find yourself having a multithreaded dialog with someone on a chat application with several topics being discussed at the same time. At least, I know that we programmers often do this. Very effective indeed!

So what about wikis? Let’s look into this now:

Local Feedback

I would say that we often use mail to communicate with each other at work since the asynchronous nature is convenient. However, one disadvantage is that important information as to why we reached a certain decision is persisted in our mail box only. Unless you are extremely organized with a myriad of mail folders, it will become difficult for you to find this mail conversation later on.

 I find that even searching for mails, as gmail states as a big strength of functionality, many times this does not work because I can’t remember the exact words to use in the search... In this case I am left with my structured mail folder hierarchy in order to find the message. After a couple of years there may be thousands of emails in each folder… But then again, perhaps this is only a problem that I have…

Another issue is that information is not published for others to read apart from those in the recipient list. At least for some topics, the information has to be brought out and written somewhere else where more people can read about it. I think that some ”non-secret” topics instead could be published and discussed directly on a wiki omitting the mail dialog. Many wikis offers comments or some kind of discussion board to be associated with the wiki page that can be used for this.

One wiki that successfully uses this approach is Wikipedia. Since everyone is allowed to enter information in Wikipedia, naturally, conflicts of opinion occur frequently. Take a look at this page for instance and please notice that it is the discussion tab. The page contains the discussion of what Inversion of Control is and how it could be explained etc. Unfortunately the meaning of the term is very different from programmer to programmer as you can see. But with discussion, eventually a mature and natural consensus can be reached as to the meaning of the term (ubiquitous language established, see this blog post). Unfortunately not yet so for IoC.

However, the essence here is that the information as of how the meaning of a term was concluded is stored locally and connected to the information itself. I.e. effective metadata! I think this is a great strength.

Naturally, there is always a decision to be made what discussions are to be held in public on a wiki and what discussions are to be held in mailing lists. I am not arguing for abandoning mail here! 

High Cohesion and Low Coupling

I would dare to say that all programmers have heard this statement (and if they haven’t, it would be time to do a little bit of studying. ) However easily stated it is not as easily achieved. I also dare to say that it takes years of programming before getting skilled enough to realize the importance of the statement as well as knowing how to apply it well. 

I have often reflected upon lately that successful communication should apply to the same principle. When explaining something to someone, we have to stay focus on the topic. Otherwise, we confuse the audience with too much information (information overload). Sometimes we need to explain a side track in the discussion before we get to our main point. Recognize this scenario? Well, it certainly is the difficult art of pedagogic and it is the importance of having common reference knowledge.

Perhaps being a little bit daring, I think the interpretation as to the meaning of high cohesion and low coupling is quite similar when it comes to communication. Looking at a story to be communicated to someone else, the main focus lies in the main message you want to get across. This information could be compact, i.e. high cohesiveness, which will make it easier to understand.  But it often relies on other information, I.e. it is coupled to the other information. Naturally you would like high cohesion and low coupling to get the main point across quickly. But this coupled information is often what makes the story complete in its context and it gives the story its nuanced and interesting flavors; although making it more difficult to understand.

Having established this interesting parallelism, let us turn an eye in the wiki direction. I have already established in the part 1 wiki blog post that refactoring of the wiki structure is an easy thing to do. This is important since it allows for us to provide pages that have a high cohesion. High cohesion in wikis is pretty straight-forward to achieve since the page refactoring support is there.

However, the thing to look out for is strong coupling. Although a good wiki should be able to update linking between pages when you change them, you may run into many fragmented pages with too many links (high coupling) to other pages. This is where your sense of structure and judgment comes into the game. I dare to say that there is no tool that can do this structuring automatically for you since no tool can predict exactly what you will write.

This is nothing new really and I believe that every good communicator has come to realize this and applies to this principle whether it is in writing documentation or merely speaking to people.

In my next, and perhaps final blog post about wikis, I will have a more practical approach as to how to choose which wiki to use (there are lots of them out there). I can’t say I am an expert of all those wikis, but at least I’ve learned some aspects to look for. So until then, stay tuned.

PS. I probably should admit that my interest in blogging on other topics recently has gained which I might prioritize writing (as well as time spent not blogging…  :( . So if you are interested in number 3 in this series, please let me know and I’ll try to speed up the persistence of that story.

I started out this web 2 series with a rather general introduction here. However I have to admit that I wasn’t very specific, nor pragmatic in this blog. This has got to change right here because for me web 2, and especially wikis, is all about a pragmatic approach:

The ability to document necessary and important information and allowing for as many people as possible to read, edit and give feedback upon this information.

This is collaboration. This is wikis.

Unfortunately, documentation often has a poor sound to it these days with the agile winds blowing in the software industry. Don’t get me wrong, these agile winds are definitely good and I think we are on the correct path here. However, I think there still is a need for some documentation. Only, the documentation has to be as agile as the process of developing the code itself. This is where wikis come into the picture as a better documentation persistence tool.

The traditional documentation approach is by using a file-based storage for content. Usually the tool is some version of Microsoft Word which is probably what 90% of what people are using. The editing functionality in this tool is excellent. However, I do recognize a number of weakness as I will note down as I go along comparing file based storage with wikis.

Published, not stored!

A wiki is always reached via a web browser. Therefore, when writing content on a wiki, it is naturally published on a web server for all authorized users to see. This is a great strength since everyone these days are used to a web browser for localizing information.

File based documentation is however often a pain to even locate on a company. Often, such files are placed on a file server somewhere in some obscure directory. Often I find that there are several of these directories too which makes the wanted document even more difficult to find.

However, an interesting approach is Microsoft Collaboration platform SharePoint. Here SharePoint is responsible alone for knowing the actual physical storage of the file and files are only provided as links to the users for download or viewing. This is a lot better approach. Unfortunately, due to licensing costs, a SharePoint solution is often not doable for smaller companies.

Refactoring structure

As when programming code it is difficult to know the exact structure before work has begun. Requirements (input data) may change or you may get new ideas as you work with the code/document. When creating a file based document, the scope for it has to be carefully considered. The information that is out of scope has to be placed in another document which instead is referred to. I find that file based documentation does not leave you much choice for actually editing the scope of the document once you have started working on it. Wikis on the other hand allow you to quite easily refactor the structure and scope as you go along. This since the actual document you are writing is split into several pages reachable via links. It is quite easy to create a new page in a wiki and link to this page which makes refactoring extremly easy. Referencing other file documents in a file document is a much harder this to do. At best you may link to a referenced file document, but this document still probably is a huge source of information so it will still take you quite some time to locate the desired information within this referrenced document.

This refactoring mechanism is one of the largest benefits with a wiki I think. It allows us to split huge sources of information in one document into several documents that are easily linked to from other pages. There is a striking similarity here to the software design Single Responsibility Principle. A class as well as a document should only have one reason to change…

No special roles, instead accountability!

Usually, a wiki does not divide people into authorized and unauthorized groups of people. Naturally, only the group with interest in the wiki may gain access to it. But aside from this authority level, everyone in the group may write whatever on the wiki pages. Usually, this would go for the whole company as long as there are no specific security reasons to conform to.

However, although anyone can edit any page, a wiki should always provide an easy way to see what was edited and by whom. This means that accountability is there since it is always possible to see and compare the different versions of a wiki page. Also, wikis should provide an easy way to roll back to a previous version of a page. 

Having security restrictions often lead to more maintenance and trouble than what it is worth. If there is no top secrets on the page, let people view and edit the information as they want. If a change was bad, well contact the person for a verbal discussion and hopefully roll back the page afterwards after you have agreed upon what should be there.

As far as I know Microsoft Word does not provide any version tracking possibility on file level so this is often added manually in the file instead. However, the SharePoint platform does give you a versioning and roll back possibility for word files. However, I don’t actually know if it is possible to compare different versions of the word file with each other.

WYSIWYG vs. wiki syntax

Microsoft Word offers WYSIWYG editing. I.e. What You See Is What You Get. It means that MS Word hides the small symbols from us that make bold text go bold and underlined etc. I think MS Word does an excellent job at this (although there are still bugs) and the application has definitely reached a mature status.

I would say most wikis are not mature when it comes to WYSIWYG editing. They are far from as feature rich as MS Word WYSIWYG and often you find yourself cussing over a behavior or a bug that you are used to in MS Word. I believe WYSIWYG in wikis will probably mature during the next couple of years and that the difference will disappear.

However, the WYSIWYG editor, if even provided, is often not what the wiki user utilizes (at least not if he is a programmer searching for control of the tool…). Instead he goes directly for the wiki syntax which is simple to use. Unfortunately, there is no standard here and the syntax varies between different wikis. Bold letter in some wikis would for instance be rendered by adding a star between the word: eg. *This text would become bold when the page is saved and published.*

And a small summary

Well, I have lots more to write about wikis but this will have to wait for a future blog post. Probably, this is even now to long for a blog post. Hopefully someone is reading this eventually. And if you do: stay tuned for more…

Andrew Hunt and David Thomas have a written a great book called The Pragmatic Programmer. This book covers so much great stuff!  Most of the time, while was reading it, I found myself sitting with the jaw against my chest in astonishment of how clearly Andrew and David pinpoints problems and recommendations in software development. I think all seasoned developers would have the same feeling since the problems Andrew and David writes about are well-known, but not very easy ones to actually pinpoint and describe.

As a side note, at the Øredev conference recently, I saw Andy Hunt giving an excellent key note speech opening up the conference. There was quite a number of fascinating subjects he talked about and I hope to be blogging on some thoughts on these subjects in the near future.

Anyway, in the book, the writers bring up a term called software entropy as a force very difficult to avoid for developers. When I first heard of entropy it was actually in chemistry class many years ago. An explosion is an excellent example of a chemical reaction that renders a very high order of entropy. I.e. the amount of disorder of atoms in the explosion is very high in the beginning but rapidly goes back to a low level of entropy. Naturally, this is due to the high amount of energy that sets the atoms in motion.

There is a striking similarity with software entropy I think. When things are heating up in a development team and we are as busy little bees to meet a deadline, entropy is bound to be high. Or at least the risk is very high that the entropy gets high. As a cause of this, Murphy’s Law might appear out of nowhere which seems to be a result of just pure bad luck. But often it is the just the result of high entropy, i.e. the disorder tends to get high as we get stressed out and several accidents happens in a short amount of time.

The writers go on with an analogy to city buildings that are of very different quality in different neighborhoods; some buildings being very clean and neat while others in another area are in a very poor state. This is the effect of “a broken window”. If one window gets broken and it does not get fixed immediately, then soon another broken window will appear; and yet another and so on. Soon the neighborhood will look like skid row and criminality increases drastically.

That this is so, even Swedish governments have concluded. I recently saw a news program stating this very fact. And in the local news paper the same very fact got stated about a neighborhood not too far from where I lived. A whole city block is going to be torn down and rebuild and as a result, criminality is sure to drop it was stated. Well, good!

I think there is an absolute truth in this and that it can be explained with our pride. If you are not proud over the neighborhood you live in, you are not going to respect either the buildings or the people that live in them. But if you feel pride over a good, esthetic environment that surrounds you, you take more care of it.

As for software development, we have the same situation Andrew and Thomas states. If you don’t feel proud over the code that is produced in the project and honor its design, the software will begin to rot. If this happens, sooner or later you probably are going to have to throw it all away and redo the whole thing from scratch.

So, as the authors of The Pragmatic Programmer so wise fully states: don’t live with broken windows. Anticipating that the design of the software is a good one, follow it instead of doing small hacks in order to save time. That time you save may very well be 10 times the time lost further down the road when someone is trying to get the once upon a time nice design to work again as it should be.

I know: Software is never perfect and this is not what the authors, neither I, are saying. However there is a great difference between delivering good enough software and doing “hacks” to the system all the time.

Unfortunately there is a driving force that often makes these hacks necessary: the critical deadline of a promise made to somewhere by somebody by someone... But the underlying reason for this is often due to a crappy or not existing project methodology which is a subject that I won’t dig into in this blog post. However, this spring I probably will write a lot more about this.