BKdotNET - Bill Knaus's Dev Blog

Better solutions through smarter code.

September 2006 - Posts

Separate your documentation to maintain system autonomy

Want to really know when everything went horribly wrong and you ended up tightly coupling something that was supposed to be modular or service oriented?  Take a look at your documentation. 

More and more as I have been digging through our team's archives, I've started to discover some of the reasons why we time-and-again are exerting additional effort to de-couple something, or end up throwing something out and starting over, or not being able to leverage something that, while being built, was billed as "reusable".  What I have found is that, while in a lot of cases we generate a lot of good doco, we're missing something.  And it's not more doco.  See the documentation is good, however its typically developed based on the project or business effort at hand.  Business efforts that may be, and typically are, driven by a very specific product or product line.  Now, the documentation itself spells out things like "...this should also be able to be used by..." or "... thereby creating a standard (enter common component name here)...".  Such statements, however, are buried within a document very specific to the project.  Or, these statements were stated (and restated to the point of folklore) by the development team when the system was built, but something fell just a bit short.

The reason why this happens typically boils down to time pressure and concessions made on the design in favor of time.  This is a very common situation is software development.  With every project, this WILL certainly occur without a doubt.  (And if you're working on a project where it's not occurring, you're probably very tired of dealing with release dates that never come... or - somehow - are very very lucky and whoever you're working for has money to spend without limitation.)

The documentation I was going through led me to realize something: with a few notable exceptions, I was unable to truly separate individual system components (services, ui modules, ui framework, etc) from the project they were originally constructed for.  Each of these components had become so wired to the original project and product it was supporting, that it was natural for the developers to cross the lines... what would be the harm? right?!  But it is exactly the harm.  And by crossing the lines, whether it be for speed or a general misunderstanding of the system design and intent of underlying components, the coupling began.

So what can be done differently?  One way to build on top of your team's creativity and desire to reuse as much as possible, is to encourage, nay, require them to document each reusable component in separate documents, laying out the requirements for their isolated system, the system design, etc.  This forces the developers to THINK about which document, which forces them to THINK about the system impact, and it no longer becomes convenient to couple these systems together because there spec lives in the same document.

I know what you're thinking... "Isn't that more documentation?"  No. More files, yes.  More doco, no - not unless you weren't creating enough documentation to begin with.

The separation of component documentation starts to drive better decisions on alternatives when the time pressure kicks in too.  Consider: the "quick" solution is to make your underlying component knowledgeable of the components that ride on top.  (Say your service now needs to have some knowledge, however big, of your UI.)  When the developer goes to document this - if it wasn't obvious before (and when working in a pressure cooker, it's an easy miss) - the realization of the coupling is apparent.  This is now the perfect time to start considering alternatives to prevent the coupling from occurring.

So - document your reusable componets.  Reference the designs for the components from your system documentation for those systems that will use them. 

Remember Always:
If it is supposed to be reusable - it doesn't "belong" to a system, but is a system of its own leveraged by multiple larger systems.