Like last post, i'm trolling the tech ed videos. i wasn't so lucky that i actually got to go this year, but i'm glad that other people got to. Not that they need to more than I but that i'm glad they did and brought back an energy level for some new ideas.
I started watching
Juval Lowy on 'The zen of architecture'
... now i am not a
BDUF kind of guy. I'm more of an
emergent design type of guy. So when he said spend a couple of weeks to look at 'all' of the use cases I laughed a little bit to myself. There is no such thing as 'all of the use cases'... i think it is the same type of assumption that the requirements are out there you just have to 'capture them'. Some would say there is
no such thing as a requirement because everything is negotiable.
Anyhow... here's what I took away:
- use very light weight diagrams that are simple to understand
- use the 'transaction script pattern' from Martin Fowler's Patterns of Enterprise Architecture
- make every object a service (when appropriate, at least at entry point to layer boundaries) because it promotes isolation and a bunch of other good stuff.
- Why layers are important and some guidelines/starting points
Here's what I would expand on for us agilists...for sprint 1 or sprint 0 if you believe in it.
- Build from the front to the back: Client first, then manager to create the stubbed in use case to identify the data.
- Choose a couple of user stories that have the most reason for volatility. For example if you are writing an application that does debit card authorizations... what about paypal authorizations or credit card authorizations in the future? Each of those types of authorizations is a variant of the authorization engine.
- Include user stories that will have a variety of authorization and authentication at different layers.
- choose a story that goes all the way through the architecture. a bad choice would be a javascript animation.
- the amount of time spent should be scaled back to 2-3 days. Obviously negotiable just don't let it turn into a full design phase.
Instead of diagramming every single use case i would just diagram the first couple of user stories that you think might have the potential to meet the above criteria. For example, I was writing an advertising campaign system and my first user story was one that calculated the rules on whether to show the customer an ad based on their number of logins. It was 1 rule out of many, it hit all the major architectural pieces (web, app, data tiers) and it gave the customer something they could look at right away and expand on.
So do a couple of use cases until you find the right ones and give everyone a feel for the big picture. do the design together with everyone... not just alone as the architect. Get the knowledge transferred to the team.
Ok now throw away the diagrams. They'll only cause confusion later on.
As an example, i had a customer contact me and ask me a few questions about what our software did in a certain scenario... the business analyst said ok i think i have thata documentation (the
PRD). I said "i'll go check the code". She came back with the document and explained what it said... i read the code and explained that she was wrong. She actually argued with me on it...
This is code that was developed and had been in production for years now... i'm pretty sure the code is right and the documentation is wrong.
Point is here... you can make all of these diagrams and communicate a good vision for your product but the only lasting documentation of the project should be the unit tests and the code itself. Everything else is just an intermediate work item and is waste. Keeping it around can often only lead to confusion and misinterpretation.
If you do have to keep it around for any regulatory reason, just be sure to go double check yourself against the real code.
Anyhow enough harping on documentation (i clearly have issues with it being misused).
Frankly my rant on compliance and audits: I don't see why an intermediate piece of documentation needs to be kept around since code itself is a document... but that's another fight for another day. I would argue that the code is just as easy to read as the cryptic jargon they put in PRDs and it's WAY less ambiguous. in fact, it's never ambiguous, it does exactly what it says it does.