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.

Writing without a Point

So I read this blog on system capacity planning yesterday.  I actually had to read it twice to make sure I did not miss something…because when I got to the end, I really and truly did not think the author had said a single thing.  At least it did not fulfill the promise of the title.

The piece was ostensibly on planning the amount of space one would need for a particular system, just the files to be stored, and it boiled down to this:

  1. Sum up all the files you plan to store in the system
  2. Allocate enough space for what you plan to store

Let me be clear, item 1 is find out the amount of storage you are already using.  It’s like in the classic “Princess Bride”, where one is left thinking, “you keep using that word ‘planning’, I do not think it means what you think it means”.  Planning calls to mind the idea of considering what might occur in, you know, the FUTURE.

I guarantee you will have a problem if you follow this advice, just as soon as one of your users creates even a single new file. BOOM. You’ve reached capacity.

Perhaps to add to the feeling that this blog was somehow more substantial, or just as a bonus, there was a mathematical formula to go along with it (paraphrased below):

If you have 500 50mb files of type x, and 1000 25mb files of type y, the formula is as follows:   (#of x files)*(size of x files)+(#of y files)*(size of y files) = Amount of space required.

Now I grant that there might be someone somewhere to whom this would be useful, but I think anyone calling themselves a systems engineer, on any level, would find this to be utterly useless.  It’s like someone telling you that, for a 25 mile trip in your car, you are going to need gas enough to go 25 miles. Ok…thanks?

If you haven’t been able to figure this much out on your own, maybe systems engineering is not for you. Or driving. Or blogging.