Retrospectives

One important aspect of agile methodologies is having feedback loops. Feedback loops allow a team to make improvements to their process, by keeping what works and changing what doesn't.

In my experience, feedback loops have a huge, positive impact on teams. Continuously improving processes, allows people to work more effectively. Making changes requires less negotiation. People are less reluctant to try out something new, because a change can always be undone in a next iteration.

Another positive result is team motivation. Everybody is encouraged to contribute. This leads to less complaining and more commitment. Especially in times of stress, looking back and clearing up the air can prevent a lot of frustration between team members.

So what is a good time to provide feedback? If immediate results can be obtained, it is best to make improvements directly. Some shortcomings are less apparent though. One way is to have a retrospective meeting with the core team. I found that just after the start of a new iteration is a very good time for this. The last iteration is still fresh in people's memory and there is plenty of time left to finnish the current iteration. Adding another meeting takes precious time though. I'd suggest a retrospective meeting can be tried at least once. If the team finds it ineffective, it can always be cancelled at the next retrospective.

Having a good retrospective meeting is hard. It can easily get out of hand and become ineffective if it has no clear structure, It can be tempting to complain about other teams, or talk about the weekends. It is most effective however to look for improvements that can be made by the team itself. A good retrospective meeting results in clear actions and an agreement on when they must be executed and by whom. It is also satisfying for every participant.

The Retrospectives Wiki has some formats to do retrospectives. Ilja's blog post on retrospective anti-patterns is a good read as well.

Effective documentation

In most software projects there is some requirement for documentation. In the few projects where there are no specific requirements it is a matter of good craftsmanship to determine just the right amount of documentation to deliver. At a minimum, it should be enough to enable another person to deploy and maintain the delivered software.

Three types of documentation I encounter the most are requirement specifications, technical designs and source code. Though I find it crucial that source code is well documented in order to maintain it properly, this post is about the external types of documentation (from the source code perspective). Browsing through source code is very time consuming. How can we write good external documentation to enable project members to quickly learn about scope, design considerations, accidental complexity and other important functional and architectural decisions?

Functional requirements

I exclusively work in agile environments. Shorter development cycles, instant feedback and iterative thinking require a different requirements process than the traditional waterfall approach. This also leads to different kinds of requirement specifications. Requirements are more and more captured in separate use case documents or stories, instead of being lengthy, hard to read documents.

In some cases however, requirements may need some form of background documentation. Consider for example a case where several functional options are explored and weighted in great detail. It can be very helpful to document these options and the decision making process for future reference.


Technical designs
For technical design documentation this is even more important. During the lifetime of a project lots of technical decisions are being made. For most technical decisions several options are explored. It is a huge waste of knowledge if these options are not documented. When new developers are added to a project I am often asked why a particular approach has been taken. Having a correct amount of documentation available does not only clearly show pros and cons for every option, It can also lead to new insights, because the reader is actively going through the reasoning process, instead of reading outcomes.

example of a classical technical design: lots of text and concepts spread over multiple pages....

Guidelines
So how to put all this information into a single document, that is still readable? In my experience, the accidental complexity of the document structure limits the allowed complexity of the documented subject. So I keep the structure as simple as possible.

maximize value
Every page must be self-explanatory. This forces the writer to be short and precise. It also provides an immediate overview of the scope and does not force the reader to browse through pages, getting out of flow. Single pages can be used for reference and taken to meetings to support conversation.

define scope

Every page covers no more than a single topic. Adding more, increases document complexity and might unnecessarily confuse the reader. If a topic is too complex to fit on a single page, I split it up in simpler concepts, or use different view levels. 

document the process

When there are multiple solutions to a problem, all considered options are described on a single page with a short analysis of each option and a judgement of important aspects. This documents earlier considerations and allows for a better general understanding of why a specific option was chosen.

be concice

A picture is worth a thousand words. It gives immediate overview and can hold large amounts of data. I try to capture every topic into a single image, using up most of a page's real estate. I add a notes section on a page to provide some context or explanation that does not go very well into the main image.

appeal to the reader

The reader has to absorb a lot of information. I always make sure that every page is visually appealing and requires little reading to keep the reader inspired and focussed, instead of easily distracted.

use proper tooling

I prefer to use graphical tools over word processors, because they allow for more creative freedom.

invest in writing

Most documents are written once, updated regularly and read often, so I spent quite some time optimizing for reading at the cost of writing speed.

write together... and enjoy!

Writing documentation should be fun. A solid foundation is the best incentive to construct a high quality document to which everyone in a team can contribute.

example of a visually appealing design that weights various options to solve a specific problem

Getting started

As a starting point I used some templates available at http://www.visualspec.org/. They can be downloaded or serve as  a source of inspiration to build your own.

My thoughts for blog

When I was about eight years old I got a second handed C64. Playing games was fun, but more and more I became curious about how these games actually worked. I borrowed some books about programming and started to create my own demos. I became heavily inspired with the challenges and satisfaction that came with building software. I knew I was going to be a software developer for the rest of my life.

Flash forward to 2010. I am 31 years old and I enjoy building business critical software over 10 years already. As a developer I led various projects with varying success. Why are some projects more succesful than others?

Over the years I discovered that building great software involves more than great developers. It requires great processes that help developers and organizations get real work done. Proccesses that challenge people to be inspired and creative. To communicate and share knowledge. To have fun and be proud of their collaborative effort. To get to new heights and super productivity.

This blog is no goal by itself. It is a means to organize my thoughts, share experiences and come to new insights. By writing I hope to learn, get more questions and explore new areas. The goal is "Kaizen Mind", to excel in what I do.

This is my first blog and I am not used to writing. Am I ready to share my thoughts? Am I comfortable showing my weaknesses? I think I am. Will I have enough topics of interests? Time will tell. I expect this post to be the hardest, so the first hurdle is taken.