Written by I was in a meeting today, the third meeting in fact, to review a document I had done. After an hour of discussion, I was able to put my finger on why our views on what should be in the pivotal document were so different, it was the origin of our understanding of what it was for.
by http://www.sxc.hu/profile/plex
I’m fortunate to work on easily the largest project I have ever worked on in my life, I’m one of about a dozen architects and my responsibility isn’t a classical one. My responsibility is really pulling together overarching views of the works of others as well as including all the natural missing common elements or things that don’t fit in other places. The nature of my document is just that, effectively an architectural summary of what is to come, with elements like integration and business understanding included. The thing that I kept having difficulty with was why were we kind of all over the map when it came to what we were expecting. This was our third meeting, and it rather than spending a couple of hours going through a couple more pages, we decided to try and figure this out from a couple of different perspectives.
During that fruitful discussion which allowed some people to have a chance to fully explain what they wanted and then to be able to have it debated and potentially identified as really belonging to another document or already existing in my document or potentially needing to be in my document, my pattern recognizer started to spin up and then DING! I pointed out that there were a couple of things that we had misaligned, between all of us, and everyone agreed.
1. Reader Expectations. We had different expectations of when you would read this particular architecture document. This doesn’t sound like much, and on a $50,000 project it doesn’t really matter. But what about a $1 Million project? What about a $10 Million project? $100 Million? What was ignorable on a small scale becomes a massive issue as you scale that up.
You need to be able to build the required knowledge set in the reader from their introduction to the project through to my document and beyond. I was originally told this would be (I’m simplifying here) the 3rd document you’d read, after which you’d read about the rest of the architectural pieces in detail. Someone else thought it would be the 10th document, after you’d read all of the pieces then you’d come here to see how they all played together. Others hadn’t thought about the reader at all.
It’s interesting to me to see what I take into account the further I go into my career. A software architecture document used to clearly mean one thing, and then it meant a superset of that, but now it doesn’t necessarily mean a superset of any of that, it really is about aligning the reader’s understanding with where we are going relative to what needs to be accomplished to solidify the understanding that came before it, present and solidify the message that’s critical at this juncture, and then to draw the map of where you are going from here. Everything else is just technical detail really.
2. The Assumed Reader. Another thing that I started thinking about was who was the assumed reader. Now this is an important distinction because if you asked everyone the question of “Who are the readers” they will correctly identify the different types of readers. But when you listened to their comments, you could start to hear a pattern and thereby identify who was the actual reader they were constantly thinking about when they were presenting their comments.
Calling this out, writing it on the board and making sure it doesn’t escape everyone’s attention can be a great way to manage this.
3. Length Matters. There is a famous quote that I don’t know who it belongs to, that the brain can only absorb as much as the backside can endure. Don’t put together a 500 page document and expect the reader to be able to read it, understand it and most importantly, remember all of it. You’re better off having a small series of documents.
Architecture documents in particular are notorious for getting wildly out of control. I’ve seen consultants for huge consulting companies just keep growing the size of the document because they are billing a lot for it, rather than having the philosophy of delivering a kawasaki ninja motorbike. “That’s it?” might be the first reaction, but then when you show the content and how efficient it is you will probably get “Wow, okay, yeah, perfect, wow, yeah, wow.”
There’s a lot of psychology I find that goes into these documents, and it’s more than just understanding what your stakeholders are expecting. It’s about understanding how they absorb and interpret information. It’s about understanding who is going to read the document so that you make sure it is written for the proper set of knowledge and skill assumptions. It’s also about delivering a quality job without leaving the client feeling like they are too dumb to ask questions.
All too often I find that we the Smart Pants Architects can forget things like, you know, readers. Thankfully experience tends to cure that.
