Steps one, three, five, and twelve

Something I say quite a bit when looking over a developer's documentation is that developers leave out steps one, three, five, and twelve when writing out directions. It's epidemic, and the reason I dread installing open source projects from the source.

Sure, there's easy_install and yum, but every now and then (like, when you're actually developing something for your job) you have to compile from source. That means you're left with whatever the developer decided to jot down and stick in INSTALL.txt.

Why does this happen?

A lot of it has to do with subtext and assumptions. Many times, it's assumed that the user has everything they need at the ready when it's time to install. Developers environments are a complex ecosystem of previous builds, custom tools, personal preferences, and helper scripts. If someone is missing just one small bit of your environment, often, the build explodes in unfun and uninformative ways.

I run into it time and time again. I run a build, and it borks. I check the requirements, see that I have everything, then start digging through the code. Ah, I'm missing a library somewhere. I get the library, try the build again, and it borks again, but somewhere completely different.

It's like those Russian nesting dolls. Except you want to punch them in their little faces.

I know what you're thinking

Did you know my background in psychology makes me psychic? It does! I know what you're thinking!

If they really care, they'll come find the community!

So, this is supposed to be some sort of secret society? Do we get sacrificial knives and awesome robes? Can mine have a pony?

There's a few issues with depending on the community for answers:

• Sometimes they're wrong. As horrible as it sounds, sometimes the people who answer the first are the most wrong. A newbie in the community isn't going to know his superstars. He'll just know that darkchy1de415 gave him some sort of answer when he needed it, and as long as he uses it only under the light of a full moon, it works.
• Sometimes... we don't answer. I've been in IrC rooms where a question is asked and never answered. We're not always around, or in a Jedi Master mood. It's not our fault: we're human!
• Sometimes, a new user can stumble into a mine field. This... this doesn't always show us in our best light. I mean, pistols at dawn is cool in the movies, but if all you want to know is what libraries you need to get a new framework running, it's less than romantic.
• Maybe the community isn't big enough. Maybe your product only has a few die hard adherents, and they're scattered all over the world. That, or they're all clustered geographically, and can simply go talk to each other rather than log on to IrC (strange, but it happens! I swear!)

Community is awesome, but when you're just trying to get the stupid thing to work, it can be a lacking resource.

Ups the cost of admission

We want more smart, curious developers. Some might say that making directions idiot-proof will lead to more idiots in our field. That might be true, but if you leave out steps, here's what the cost of admission is:

1. Happening to have the right libraries installed from the start
2. Happening to find the right person who can walk them through it
3. Being able to guess really well
4. Being patient enough to dig through code every time something goes splat.

So, we end up with people who are extremely lucky, or have the patience of a corpse. Yay.

More chance someone will screw up and bad mouth you

Nothing makes people want to use your product more than a Google search filled with rants about how they couldn't even get it working.

What to do?

Clean your room

Try your deployment on a clean environment. Whether it's a virtual machine, something running under Bootcamp, or you finally actually use that spare server you requisitioned a few years back, make sure it's clean and try your app out. All the weird things you've forgotten about should pop up, as bright as day.

It's not your grandma, but it'll do

Find someone else to step through your directions. Try and match the lowest common denominator of who might use your app. Sure, it's probably not grandma, but that junior dev might be a good resource to exploit.

Watch them try to execute your directions. WATCH. Keep your mouth shut and your notebook handy.

Fail gracefully

If you have a few things that seem to be problematic, try to fail gracefully. Check for what you need, spit out a sensible error. Don't make me crawl through your code in hopes that I can figure out what's going wrong, what weird thing I've missed.

Chances are, I'll just go elsewhere.