User Manual Driven Design

Today I want to follow up on my recent blog entry about conceptual product design.

I have worked in various projects starting from very small ones with just 3 people involved up to rather big ones with more than 100 developers. A very interesting thing I noticed was that as bigger the project was the desired outcome was more and more unspecified. The requirements got more and more abstract and less people knew what problems the system should solve, how they should be solved and how the solution should look like.

But in fact in every project only one thing is really important: the outcome. Software engineering is NOT about defining good architecture or writing robust code or something like that. Software Engineering is about making the customer happy. And the customer is happy if the software fulfils his need in a comfortable manner. By the way you should take a look that you are not getting into troubles when you have to change something later on. Therefore good architecture is quite nice. In big projects I often had the feeling that people are paying good architecture and code which fulfil documentation standards and fit to checkstyle definitions more attention as they are giving to the output and functionality they produce. This is very dangerous. It can happen that you have a piece of wonderful software at the end which does nothing useful to the user.

This brought me to the very expressive idea of User Manual Driven Design (UMDD). I would define UMDD as a software engineering process to organize project or product development in an extremely user oriented way. It concentrates on the principle of “Getting the RIGHT things done”!

UMDD is simple. In fact you can express it in one sentence. The basic rule of UMDD is:

Start your project with writing the User Manual together with your users.

Examples
In fact I tried UMDD basically two times by now. Both times it have been small projects were I had quite much influence on the project organisation. One project was done during my time at the polytechnical university of Hagenberg. We built a web system in the medical area. I was responsible for the conceptual product design and requirements engineering. I was thinking how I can communicate to the medical stuff at the customer site and to my team members in development using the same artefacts. I started with drawing nice Visio drawings containing big sequence diagrams and a simple form of class diagrams. But it turned out that the medical stuff did not understand anything with it and it was even to abstract for the rest of the team because they kept asking me how it should look like. So I just started writing the handbook and added screenshots from an html prototype to it. I wrote chapter by chapter and the medical stuff had a change to take a look. I also showed the html prototype to them and they were able to do a few clicks at it. We started development after the technical evaluation and at that time the user manual already had about 50 pages describing quite fine what to develop.

In other projects together with one of my most important customer plus Media GmbH we are working in very similar way. We do not write actual user manuals because we do not have them at all and I strongly recommend not writing any documents which no one uses afterwards. Therefore my customer is providing me screenshots with some informal documentation what should happen within the screens. Additionally we have defined some cross cutting issues which have to apply to all parts of the system. It is also an extremely productive cooperation. In addition we know each other well in the meantime. So we have a common base of communication which makes teamwork easier. I strongly suggest for all parties involved in a project to maintain a long, cooperative and fair partnership. It is much easier to work successfully then.

Conclusion
Some rules for a successful project:
1. First write the user manual and then start development.
2. Tell the developers WHAT to develop.
3. Use the same communication artefact for users and developers.
4. Maintain long, cooperative and fair partnerships with your customers or your contractors.

Outlook
Because the entry already got rather long I postponed my argumentation why UMDD is better than collecting requirements and use cases and using them as the base for development. I know that this idea is not complete by now so that it would be possible to pray it as a religion. I will also follow up on how this can fit together with other techniques like test driven development or prototyping. I still have to think about it in more detail and how to integrate it well established processes and so comments on it a very, very welcome. I will also try to integrate this idea more and more in my current projects.

Special Thanks
Special thanks also goes to Alexander Buchmann working at Siemens for his input to this idea.