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.