I’ve always been interested in how you write down software designs so that others can use them. If I’m completely honest I will admit that I find that question more interesting than how you come up with the designs themselves (although I believe the act of writing them down is inextricably intertwined with coming up with them). As Len Bass, Felix Bachmann, David Garlan, James Ivers, Reed Little, Paulo Merson, Robert Nord, Judy Stafford and I work on finishing the second edition of Documenting Software Architectures: Views and Beyond, architecture documentation is on my mind more than usual these days.
I’m in Seoul, Korea, as I write this. Yesterday I rode the Seoul subway across the city to do some shopping, and I used the subway maps in the stations and on the trains to guide my journey. As I sat on the train as it made its way from station to the station, I stared at the system map inside each car:
It occurred to me, as it has in the past, that subway maps are very good everyday examples of architecture documentation. A subway system architecture isn’t a software architecture, for sure, but it’s certainly an architecture. I started wondering what parts of our Views and Beyond approach todocumentation I could recognize in a subway map and the associated pieces of information the public can find in a subway station.
– Paul Clements