Why documentation doesn't matter?

Well, it's not really true, it does matter - just not post mortem. It does tell the developer what to do - sometimes even how to do it. It tells the tester how to test it. After the release it's no longer valid nor accurate for anyone to use. Wanna know why?

A simple case

Imagine for a second there's a new position you just stepped into. It's this glorious application that everyone keeps talking about on the 'net. You took a position in one of the teams because you were certain that this can't be wrong - people have been doing that for years so good established processes and a proper technical documentation will be accompanied by a proper introduction training - something to take the edge off from new hires.

Introductory shock

I mean, woooow!!! You just came to the office, suddenly you realize nobody knows who you are, nobody seems to care. People seem to be rushing for no apparent reason through the floors - it's nothing like the place you've envisioned. But that's ok, right? You came here to do the job so let's get that notebook and let's get this show on the road!

Still positive, still passionate, still a foreigner - but you feel this is your chance! In this company, in this corporation there are endless possibilities! Here you will shine!

The second disaster

Ok, so you finally know where you sit, you've got your shiny new notebook on your desk trying to figure out what you've been given, trying to get your familiar tools installed so that you can finally kick start that 'being a developer at ' dream come true.

First of all you don't get to install whatever you want on company's property. No no.. There are rules in place preventing you to utilize whatever power Today's software market has to offer (commercial or OpenSource) so you're kinda stuck with what your new employer has carefully selected for you. You keep telling yourself that it's just a matter of time, that chemistry doesn't happen over night and that you'll get used to it. Why wouldn't you?

Anyways,... There comes the big moment: you're getting the sources! Obviously it's all going to be professional, high quality, top-to-bottom properly designed and brilliantly described in a few pages of perfect documentation. Well.. Our heroes rarely live up to our expectations and my friend this ain't no different. Suddenly it looks like some soft-skill course is more important than getting things done (the famous 'complete this course by today midnight or you'll be terminated' email floating around). Product training is something nobody heard within this walls since the company grew from 7 enthusiast to 1300 employees most of which have better things to do than to sit here, with you and explain obvious things - that seems like a giant waste of time, right?

So you're a professional, right?

And so you've got the code, you've got all the tools you shall need, you have access to the password-protected Maven repository and by all means - let's get to hacking! Obviously we need to start that thing first on that shiny new piece of equipment to compensate the lack of documentation with a debugger session. But wait! What's that error during compilation? Does that look like a broken test? NO!!! It's the code in one of the core modules that a colleague from abroad committed a few moments ago - just forgot to add that new class to version control before and it just so happened it landed this way on your machine. No worries! This is a good version control system so people's email addresses are there to chase that person and to give 'em hell! And so you do:

Dear John,

I've tried compiling our solution a moment ago but it seems like the code you committed Today lacks one of the new classes. Can you please check what's missing? Thanks!

Best regards,

Francisco

One should thing that such an error like "code does not compile" would be spotted by some continuous integration environment where it's constantly tested to meed the high quality standards everyone talked about on the interview. It just so happens that the server CI is on went down 3 weeks ago and nobody noticed. Since everyone sat so far in the same room with nice flowers and A/C if John would commit the code with errors Sally would come over for a coffee and tell him to fix it. This time John is some 6000 miles away on another continent and just called it a day.

No worries - I'm a professional!

And so I'm capable of at least learning the inner workings of the system by going through that clear-cut set of unit and integration tests the project is obviously equipped with. So where are they?

The real life

As with any corporation there are rules: you don't moan, you be creative, think outside of the box, be proactive - and all that politely and politically correct. Following this path 2 weeks later you've got the application running, the database it talks to is across several VPN connections so it's ridiculously slow, most of the external systems don't respond since their security just isn't setup for your location (you being the new developer in the team abroad) and quite frankly you start to miss on the boss that told you you can go to hell because he's not going to be giving you anything you didn't earn with blood and sweat and tears.

So why doesn't documentation matter?

Plain and simple: if you think you have any form of documentation other than the application code itself you're mistaken. Anything talking about the code, telling you how things are is bullshit and does not mean a thing. Wanna know why? Because your compiler doesn't read wiki, it doesn't have access to your email account nor does he care at all about Word documents and Excel spreadsheets. All it's interested in is the funky looking wall of text in source files - that's the only specification, the only documentation, the only rule book that will tell you everything.

So for the love of God: KEEP IT CLEAN! You're gonna need it 'cause you're gonna read it over and over and over and over again. If your co-workers (co-located and those miles, miles away) don't understand the need for keeping things clean tell them it's important to you, that you don't want to work in manure.

And if they will not listen - to hell with them! Tell the world how things are so that the next person drown by the lucrative perspective of working in young and highly motivated team will stay away. Let other learn from your experience.

Post scriptum

If any of you felt this matches any of your previous experience I rush to say it's fiction (well at least some of it). The situation as a whole didn't happen at all (would have been a disaster and a case for a shrink afterwards :] ). It's just to underline the importance of clean code and the fact that the code is the ultimate documentation out there. Don't undermine it.