Spec Docs (or "Have you looked at the brochure?")

May 6, 2018


My team wants design specifications documented. What we currently have is an interactive InVision document that shows the ideal / demo version of the website. This InVision app is what is known as a high-fidelity prototype and has its place in the normal development of a product. When we ask for specifications for the website we are told to look at the InVision document. This document is nothing more than images of what the website will look like, with some clickable regions that link to other images.


To put this into perspective, let’s look at this from the standpoint of building a house. The designer, who we will call Dobson, has a brochure for the ideal house that our client wants built. Dobson and the rest of the sales team are using this brochure to try to sell plots to home owners. This is exactly how you would expect to use a brochure.

To actually build a house, you need plans, blueprints, and a good idea on how everything will be laid out. Otherwise you run the risk of wasting money and time.

The Exchange

What follows is a fictitious exchange between designer, Dobson, and the construction team.

Dobson: So there you have it. It’s beautiful, no?

Team: Yeah, it’s great. Can we get a copy of the designs?

D: Sure, I’ll make this brochure available to everyone on the team.

T: No, we’re looking for actual designs or plans. We need the layout of the interior and exterior, as well as the attic, storage, and garage.

D: Oh, just look at the brochure. It’s all there.

T: It’s not. The brochure lists five bathrooms, but only shows one. We need to know its dimensions, and it would be nice to know what fixtures are expected. This one you have here has a double sink. Do they all have double sinks? These are questions we need answered so we know how we’ll need to do the piping.

D: Well obviously the brochure doesn’t have everything like that, it’s just a brochure. I expected the construction team would be able to make decisions like what kinds of pipe to use. I don’t really care if you use copper or PEX.

T: We’re not talking about the types of pipes. We need to know what’s in the bathroom so that we can put the piping in the walls. That way the hookups are there when we go to install the sinks, tubs, and toilet. The same for light fixtures and electrical outlets.

D: You can look at the brochure, see there’s the sink, and there’s the lights. I’m not sure what more you’re looking for.

T: That’s still only one bathroom. What about the other four?

D: Look I’m not here to tell you what bathrooms are supposed to look like. Just make it like the brochure.

T: Fine, let’s move on.

D: Great. There are probably going to be hundreds of these houses. Each owner can pick their own color palette before-hand. It’s only going to be two colors at first, so it should be easy.

T: Wait, so now there’s a bunch of houses each with it’s own color scheme? We thought that this first house was the prototype to show investors.

D: Oh no, we’re going straight into building all of them.

T: Fine. For the color schemes, we need to know what the primary and secondary color affect.

D: Have you looked at the brochure? It’s all there.

T: It’s not all there. The brochure is only one house, with one color scheme. It has white walls. Do they all have white walls?

D: Well yeah of course.

T: Okay that’s something. We still need a comprehensive list. It looks like the floorboards, hand rails, doors are all the same color. Are those all the primary color?

D: Yes.

T: Right. We don’t see any other colors. Where’s the secondary color?

Dobson grabs the brochure and starts flipping through it, going back and forth trying to find an example. Finally, he holds up the brochure and points to the air vents, which are a different color.

D: Here, see the vents will be the secondary color.

T: Is that it?

D: Yes, for now.

T: Wonderful.

D: One last thing. I noticed that light switch and outlet covers you have don’t match the ones in the brochure.

T: We’re using industry standard covers because that’s what we have. They can be found everywhere.

D: Use the ones in the brochure. It’s really not hard to replace light switch covers, it’s just two screws.

T: Replacing them is not the problem. We physically don’t have them. If you can supply them, we can use the ones in the brochure.

Dobson hands over a stack of photos showing the light switch and outlet covers.

T: These are photos. We can’t do anything with these.

D: I guess I can have my people build them. I can probably have them for you in a few weeks.

T: A few weeks?! Don’t bother. We’ll do it ourselves and have them tomorrow.

Banner Photo by Daniel McCullough