This is a single archived entry from Stefan Tilkov’s blog. For more up-to-date content, check out my author page at INNOQ, which has more information about me and also contains a list of published talks, podcasts, and articles. Or you can check out the full archive.

Architecture Documentation

Stefan Tilkov,

My friend Gernot Starke is delivering a presentation on communicating a system's architecture to the team and stakeholders. Good talk, as usual, very much focusing on "soft" issues. One question from the audience from the audience was interesting and went unanswered because it was out of scope, but it grabbed my attention: What's the right tooling to document an architecture? MS Office, i.e. Word? Docbook?

Considering all the different tools that I have used in the past, my vote would be to use a Wiki, without a moment of hesitation. Seriously, why would anyone willingly choose something else without being forced to do so?

On November 8, 2008 4:49 PM, Chuck said:

I agree with using a Wiki, although I’m typically forced to use word documents.

An interesting documentation example I saw recently is the DDD Sample Application (e.g. http://dddsample.sourceforge.net/characterization.html). I like the use of hypertext to connect concepts with the code base.

On November 10, 2008 9:54 PM, Matthias Bohlen said:

Recently, Jeff Sutherland (co-inventor of Scrum) said that after two years of discussion about architecture formats, they chose a very innovative one:

Each person who is responsible for a particular component…

  • paints a few slides using whatever tool she likes
  • projects them onto a big screen
  • puts herself next to it
  • records herself with a video camera, explaining the component
  • puts the movie (including audio) into the wiki so that everybody is able to watch it

This ensures a high communication bandwidth while keeping the authoring effort low at the same time. Pretty cool!