Use of Posters and Flow Charts in Lieu of Prose for Documentation - Is a Visio is Worth a Thousand Words?
We've got fairly powerful (but some say, complicated) Code Generation process that uses XML Schema along with (with thing) an interesting use of WSDL with an alternate binding. Voyager is our flagship snazzy eFinance Server and using standard modelling tools (XMLSpy, VS.NET, etc) one (business person, computer wonk, whoever) 
can sit down and model all their Domain Objects, Request and Response Messages in XSD (nouns) and associate them with actual Voyager Operations (verbs) in WSDL. Then rather than using a SOAP binding (if they were to talk to a Web Service with these messages) they can use a Voyager Binding in WSDL. Then we run a Code Generation process on the WSDL/XSD and generate all the C# objects, messages, proxy layers, Word Documentation, yada yada yada.
All this is built into our Continuous Integration Process so when one checks in an XSD into the Version Control System those artifacts are automatically built and made available to others.
Since this is a fairly complex experience to the non-XML initiated, a lot of prose has been written and a lot of hand waving happens to explain this process.
Some users though felt the prose was, well, too prose-y, and wanted a quicker way to grok the material.
So, I spent two days in Visio creating a 44" by 34" poster (FOUR 11" by 17" pages or one big Plotter plot) that has the source of the XSDs, the source of the generated objects and stacks, as well as diagrams describing the relationships between objects when they exist in a running process.
People can look at the code generation progression as well as the composition of elements:
- Declarative XSDs (multiple ones, lots of imports, namespaces and custom attributes)
- Generated C# code
- Assembly names, class names, .NET namespace names
- Resulting compiled assemblies
- How those final build artifacts exist in a running system
I've finished the first draft (this screen shot is to give you an idea of the scope and size of this poster) and will share it with the team tomorrow.
How often do you or your groups create one large diagram instead of writing one or more large documents? When are architecture & design posters useful and when are just trouble?
About Scott
Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.
About Newsletter
Comments are closed.