There are a million blog posts about vague client requirements… and this is one of them.

As a designer, this is the design or spec document that you want to give your programmer:

Of course, that’s the ideal scenario — a document that perfectly covers the feature. Nothing missing, nothing extra, nothing incorrect. (Har, har.) In reality, this is closer to an actual document:

Design or spec document versus ideal feature needs

Woah! Look at all that red area with undefined functionality. Of course, this is still a very straight-to-the-point documentation, with no extras and no fluff. In reality:

Design or spec document versus actual feature needs

As a designer, your design or spec document is not perfect, and that is fine. We are making a product, not documentation. It is expected that specs are ambiguous, incomplete, have non-essential remarks, don’t cover edge cases, etc.

So, as a designer, you (really should) expect questions. In your mind, you probably see this:

Ideal questions about incomplete design spec

Wouldn’t that be nice? Three big questions, everything answered, off to the coding land! But how exactly did the questions get so big to cover this much unanswered territory (and were still quick to answer)? More importantly, if they were so easy to ask and answer, why weren’t they covered to begin with?

Well, that’s because that’s not how questions work. Questions are a tedious, imprecise ordeal. Questions are human and humans can only hope to get through them quickly.

Actual questions about incomplete design spec

Some questions turn out irrelevant, some are already covered, some overlap. And it still doesn’t even remotely cover it all!

If I had to broadly advise designers about their feature documentation, then:

  1. Be ready for lots of “stupid” questions. Programming is about solving problems and solving problems requires clarity, no matter how obvious the answers are. Be ready that your documentation isn’t nearly as good or complete as you expected.
  2. You may have a clear idea in your mind, but something blatantly obvious to you may be a novel concept to someone else. I highly recommend you to read the Door Design Problem.
  3. Don’t rush the answer. Sometimes you’ll get a question you hadn’t considered at all and you’ll be tempted to answer straight away because you’re put on the spot.
  4. Iterate on feedback. It’s cheaper to change things in a design spec than it is in the code. You don’t want to discover “incorrectly” implemented features because you didn’t explain them right.
  5. Ultimately, just tell the programmer — do it yourself. You cannot answer every detail, and it’s time to surrender the design flag.

Finally, a feature is not made for your programmer and they don’t have to like it in all it’s unimplemented glory. It is for your players. Allow your programmer to riddle your design full of holes. Criticism is good. If you can anticipate and work with the worst of your feature, the best of it will shine. Often you’ll find that you thought something simple and straight-forward is actually complex and highly intertwined. Besides, considering all the details will give you better time estimates.

And most of all: be weary when the programmer doesn’t ask any questions. We’ve established (hopefully) that your design isn’t perfect. Short of being a mind-reader, neither are your programmers. Don’t trust an unqualified “will do”. Someone might be getting in over their head.

Question size versus documentation size


Requesting Features Is Hard

Leave a Reply

Your email address will not be published. Required fields are marked *