Search results matching tags 'Best Practices', 'Pillars', and 'Documentation'

Checkpoint – Four pillars down, Three to Go

drsql — Thu, 14 May 2009 22:32:51 GMT

With the previous post on the fourth pillar, I have reached the “end” of the design posts. To review, these were:

Coherent – cohesive, comprehendible, standards based, names/datatypes all make sense, needs little documentation
Normal – normalized as much as possible without harming usability/performance (based on testing)
Fundamentally Sound – fundamental rules enforced such that you don’t have to check datatypes, base domains, relationships, etc
Documented – Anything that cannot be gather from the previous four is written down and/or diagrammed for others

When you are looking at a database that you have NO idea what it does, or why it exists, these things I have so far outlined will be the sorts of things you notice first. If NOT(normalized AND understandable AND data protected AND documented) = TRUE, then you will feel it and really hope that you are an hours based contractor with your highest rate and a set time to pack up and head elsewhere richer than a . If the opposite is true, being an employee for that company is where you want to be.

Looking back, one thing stands out to me as a possible (reasonable) concern. I didn’t include anything about “complete”. By the time my next edition of “Pro SQL Server 2008 Relational Database Design and Implementation” rolls around, it might. However, my initial thinking was that these were characteristics beyond the basic “it must at least work” benchmark that should be obvious to any semi-logical human being (which I suppose limits the gene pool, but at least most readers of my book who don’t misunderstand the term data model as a social activity will meet that requirement). I sort of hope it goes without saying to those folks that a database cannot be a good database without it serving the needs of the users. The only thing I am trying to point out in these pillars is to ascertain how cleanly the database does that task.

I also think that I might do some rearranging to make Normal and Sound Theory as the foundation and just have six pillars. Either way, things will change.

For example, if you were modeling a time entry system, no matter how normalized, understandable, data protected and documented your system was, if you failed to capture who was entering time and the employees never got paid, your database would suck. In fact, I would go so far as to warn you to expect a large group of people at your door with pitchforks and torches ready to give you an alternate meaning to the term “perforated colon” or at least a crash course in database design/implementation.

The thing is that anyone building a system to capture employee’s time and getting them paid would do a certain set of things, even if the entire system was done on paper. The fact is, rare is the case that a system is created that won’t minimally do the task that was originally asked for in some reasonably decent manner. In fact, this can, as a person who wants to get it done right, be your biggest enemy. Getting it done well can easily take a back seat to just getting it done. Worse still, there is some truth to the logic to this statement. As the old saying goes:

Better is the enemy of good enough
Admiral of the Fleet of the Soviet Union Sergey Georgiyevich Gorshkov

But the problem with that saying is in the interpretation. What is “good enough”? To me, this lack of a definition of good enough is what derails a lot of projects where this is the sentiment. If you don’t define “good enough” as being a solid platform for growth and usability, this is pretty much a half truth, and a half truth is far more difficult to deal with than a complete lie.

And then she understood the devilish cunning of the enemies’ plan. By mixing a little truth with it they had made their lie far stronger.
C. S. Lewis, The Last Battle

As the architect of a system, just getting it done is NOT the goal. It is a very important step along the way to the actual goal, but it is not the goal. Malleable software that can grow and expand to meet the needs of the users now and in the future is the goal that serves your customers best. The cost of creating and managing software over months and years is often a lot more than is initally thought. The cost of having a human do the work on paper and filing cabinets can be more efficient and cheaper than poorly written, hard to manage software. Too often computers just turn a bunch of paper forms into bits and bytes rather than streamlining a process to make the computer do the work for you. Sometimes it is just protecting the jobs of others that causes this, but the fact is, eliminating a job of a person who pushes a button over and over every day will allow someone to be hired to do actual work (even the button pusher!) that can add to the bottom line, not simply waste resources.

The pillars were conceived a “catch phrase” to help think about how we can ease the process of getting the system built, created, and eventually maintained in a manner that helps the eventual product be useful for years to come, and in the process help you to become a respected member of your team, not the one who is talked about as a “good riddance” once you have finally left the company.

The fourth pillar – Documented

drsql — Wed, 15 Apr 2009 21:52:00 GMT

This blog probably won’t stir up a hornet’s nest or anything, but I would also expect that it would be the least popular in practice. The person who feels they can disagree with the need for a reasonable amount of documentation is probably nuts. In the first post, I defined documented as “Anything that cannot be gathered from the previous four is written down and/or diagrammed for others”. And yes, I know documentation is more boring than a whole oilfield of derricks. So let me give you a life lesson. Documentation is fun when it is done BEFORE you build.

Yes, you heard me. If you have chosen names for things that seem right, the definitions you make may in fact just fall out of the name. So it isn’t that much work. The payoff is probably a lot better than you might imagine. And be careful though, TOO much documentation can easily be worse than no documentation. Sometimes systems have so much documentation that it is impossible to know how to even find information, or there are conflicting bits of documentation. Keep it sparse, just enough information that you communicate what was on your mind when you were designing your objects. Some example benefits that I find:

Names can only be so descriptive – You only get 128 characters for a name, and if you get close to that your users are going to beat you with whatever they can find handy. Name should be succinct versions of the definitions.
Names should not usually include purpose - Purpose can be tricky. Who wanted this, why they wanted it, and how it is to be used can only be documented (or mined from the code later, I suppose, if you are REALLY patient and your programmers use really good comments.)
While documenting your objects, you will be forced to (shudder) think one more time about what you are documenting -Writing down your meaning of what you have just designed after you are feeling good about it gives you a chance to give it one more look over, and this time in context of other stuff you have done. I often find one or two things per hundred (at least) that I go…maybe I was wrong. (Of course when I say it the sound in my head is more like Fonzie admitting he was wr..wr..wr..wroo…wwwr..Hey a guy has to have some ego.)
Documentation should be written in a language that all users can understand – Sometimes in our names we use clever jargon to make the names more concise. Inheritance is a good example. Ask the normal user what inheritance is any they will start fantasizing that their parents just passed away (in the best possible manner, of course) and left them a billion dollars. Clearly this is unlikely to be the meaning of this word unless you are creating a system to create a last will and testament.

The fourth is the magical moment (wow, too much Disney ). You have your design you want to implement. Your analysts and users are checking out the design to make sure they “approve.” They see a lot of names, fine. They see some diagrams, decent. They read your definitions and wait. What do you mean by “this attribute is here for X”? Did we agree to that?

Well, yeah, I thought you did, you will indignantly think, but sometimes, no matter how sure you are that you are right (and really no matter how right you are that this was in fact the design you had agree on) the realization that a communication gap the size of you and your parents was somehow opened up and things went sideways.

I feel like I am repeating myself, but for you Agile guys, I don’t mean documenting things to death, or even spending all that much time. If you are creating 30 tables with 10 columns on average, and 20 relationships, you only need to document 320 independent items. Add a bit more to the documentation for constraints, and then for processes, and you might have two hours of work. And if you DO find this taking too long, either you have messed up the first Pillar: Coherent or your team has real communication problems that can’t easily be solved by reading this blog. And the more Agile you are, the more important coherent communication (which includes documentation) is. What happens if you get it wrong and cannot ship after a sprint because you didn’t get clear direction and your team didn’t realize it until they started seeing the “results”? Pretty sure that can’t be good for the manifesto.

So yeah, all I am trying to say is that documentation is communication. Not just to you, not just to other programmers, but to future programmers, users, and even a future version of yourself that you would treat better if you could see the pain in his (or hers) eyes.