Woolly Writing

I have been working with business intelligence systems for over 15 years,  in report development, systems administration, technical documentation and leadership roles. One of the mistakes that I see being made repeatedly is documentation/design without a true understanding of what can and can’t be done in a given system, or how a system is actually configured.

I have been involved in projects where the people designing the internal security aspect of a system just did not understand certain critical points.  Being called in to review at the end, but not necessarily advise at the beginning, it gets a bit sticky to point out that their design will not work. Based on the reception that some of my constructive criticism receives, it feels like I am expected to review it and say, “Looks great!” even though there are glaring issues. They are driving the train off the tracks and I am supposed to give the “thumbs up”.

I have been in meetings where people have talked for 20 minutes about such and such aspect of a system, until I finally have to point out that there is no such thing in this particular system, and perhaps what they mean is a whole other thing – referred to by a different but similar name, and with different functionality..?  Politely, of course.

Terminology actually matters if you want people to understand you.  

Folks seem to get by using woolly language to describe things and processes, in what should be one of the most precision oriented areas of writing:  technical communication.

Due to the lack of real detail, often caused by a lack of real understanding,  when it gets down to actually making something, it is not going to be clear to the developer what, exactly, needs to be done.   This of course will only complicate the question of *how* to do it.

Many people would say that this is part of why ‘Agile’ development has become so popular, and I would agree.  But it is a solution only up to a point.  You can have a great chat with users & designers,  create a document stating briefly what is required, do a compartmentalized bit of development, and be back around to the customer to show them results quickly enough to correct any major issues.

But you cannot, and should not, expect the customer to really have a deep technical understanding of the design, it just isn’t their job – they are focused on other things. Some customers are very savvy, but there will always be areas where the customer is NEVER going to have a really great grasp on how a particular thing should work in the background. In those cases, developers and designers have to have an understanding of what can and cannot be done, and be able to express it with the right words, in order to properly build new software or configure cots, etc.  Without that, even if the customer is nodding at everything you show them, you can still risk getting all the way to the end of a project only to discover that some subtle functionality of the system, such as the security model, just is not designed and built correctly.

So the missing link is that most elusive of employees: one who can both understand the system at hand, as well as express it clearly to the customer.