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.