Painless Functional Specifications/Design Docs

CPUFreak91 · **Posted:** Sun Feb 22, 2009 7:21 am

This is a commentary on Joel Spolsky's post on Painless Function Specifications/Design Docs (from Joel On Software) with comparisons and similarities from real-world experiences on both our parts.

Joel Spolsky wrote:

Specs are like flossing: everybody knows they should be writing them, but nobody does.

Why won't people write specs? People claim that it's because they're saving time by skipping the spec-writing phase. They act as if spec-writing was a luxury reserved for NASA space shuttle engineers, or people who work for giant, established insurance companies. Balderdash. First of all, failing to write a spec is the single biggest unnecessary risk you take in a software project. It's as stupid as setting off to cross the Mojave desert with just the clothes on your back, hoping to "wing it." Programmers and software engineers who dive into code without writing a spec... are terribly unproductive. They write bad code and produce shoddy software, and they threaten their projects by taking giant risks which are completely uncalled for.
http://www.joelonsoftware.com/articles/ ... 00036.html

I've written some code that had a brilliant design (I do say so myself

), but I never bothered with specs and the programs usually worked like crap. When I wrote at least 3 paragraphs on what I wanted to the program to do and how to do it, my programs work better.

Joel Spolsky wrote:

The most important function of a spec is to design the program. Even if you are working on code all by yourself, and you write a spec solely for your own benefit, the act of writing the spec -- describing how the program works in minute detail -- will force you to actually design the program.

I've done some fifteen one-man projects that were a great idea on paper, but when I sat down and started coding, without designing anything first. After about a week, my code sprawled so much (due to having no design and, frequently, beginner's inexperience) that it looked like fungus in a compost heap--it covered everything but doesn't have much purpose (except to decompose stuff), and it definitely isn't pretty.

Joel Spolsky wrote:

When you design your product in a human language, it only takes a few minutes to try thinking about several possibilities, revising, and improving your design. Nobody feels bad when they delete a paragraph in a word processor. But when you design your product in a programming language, it takes weeks to do iterative designs. What's worse, a programmer who's just spend 2 weeks writing some code is going to be quite attached to that code, no matter how wrong it is.

This happened in Bible Dave. Because we didn't design it too well, there were pieces of code that we had to scrap, which was very hard. We succeeded in getting rid of a lot but, even today, there's some code in there that we were unable to get rid of because so much effort had been put into it. It didn't matter that we needed better code, we just felt it wasn't right to scrap something that a team member had literally spent days working on. Had we had better english design docs that covered more nitty gritty and code-related aspects, we wouldn't have had to waste time figuring out how to get someone's obsolete code to work with our new code (or vice versa).

Joel Spolsky wrote:

When you write a spec, you only have to communicate how the program is supposed to work once. Everybody on the team can just read the spec. The QA people read it so that they know how the program is supposed to work and they know what to test for... The developers read it so that they know what code to write. The customers read it to make sure the developers are building a product that they would want to pay for...

When you don't have a spec, all this communication still happens, because it has to, but it happens ad hoc. The QA people fool around with the program willy-nilly, and when something looks odd, they go and interrupt the programmers yet again to ask them another stupid question about how the thing is supposed to work. Besides the fact that this ruins the programmer's productivity, the programmers tend to give the answer that corresponds to what they wrote in the code, rather than the "right answer." So the QA people are really testing the program against the program rather than the program against the design, which would be, um, a little bit more useful.

At the start of development on Bible Dave, communication wasn't too much of a problem. Later on it became more apparent (in hindsight) that a better spec would have helped both developers and beta testers. When I was doing my own QA, it would have helped to have a spec handy that had been updated frequently because I had no idea what some people's code did. They never responded to email, so it took me a long time before I figured out how to interact with their code.

Joel Spolsky wrote:

It's OK for the first version of the spec to leave open issues. When I write a first draft, I always have lots of open issues, but I flag them (using a special style so I can search for them) and, if appropriate, discuss the alternatives. By the time the programmers start work, all of these need to be stomped out. (You might think it's OK to just let the programmers start on all the easy stuff, and you'll solve the open issues later. Bad idea. You will have enough problems resolving the new issues that come up when the programmers try to implement the code, without having old open issues around that you knew about in advance and could have solved then. Besides, the way you resolve anything non-trivial may have a major impact on how the code should be written.)
http://www.joelonsoftware.com/articles/ ... 00035.html

Just thought you'd enjoy reading this

. I don't really have any comments. Actually I do. I used to believe that all open issues needed to be "closed" before any coding could start. Seeing as how that didn't work, I/we went on to code with a few open issues and nothing wrong happened because of it. I (at least) felt a bit uncomfortable with open issues (and I still do, but I decided that I'd try to net let it affect me... long before I read Joel's comments).

Joel Spolsky wrote:

While you're writing a spec, remember your various audiences: programmers, testers, marketing, tech writers, etc. As you write the spec you may think of useful factoids that will be helpful to just one of those groups. For example, I flag messages to the programmer, which usually describe some technical implementation detail, as "Technical Notes". Marketing people ignore those. Programmers devour them. My specs are often chock full of "Testing Notes," "Marketing Notes," and "Documentation Notes."

While developing Bible Dave, I drew up a design doc with both programmers and artists in mind. Naturally the programmers were given more detail, but I think it helped (didn't it, Lava, or did you never read the design docs?

).

During Open Fire Gold's development both the artist and the programmer audiences were heavily addressed. While the wiki page was rather short, 49% of it was aimed at the artist, Jeff. Another 49% was directed at myself, the coder. The remaining 2% was for idea brainstorming and other things.

Joel Spolsky wrote:

So. Specs are good, but not if nobody reads them. As a spec-writer, you have to trick people into reading your stuff, and you should also probably make an effort not to cause any already-too-small brains to leak out through eye-sockets.

Tricking people into reading your stuff is usually just a matter of good writing. But it's not fair of me to just say "be a good writer" and leave it at that. Here are four easy rules that you absolutely must follow to make specs that get read.

Rule 1: Be Funny

Yep, rule number one in tricking people into reading your spec is to make the experience enjoyable. Don't tell me you weren't born funny, I don't buy it. Everybody has funny ideas all the time, they just self-censor them because they think that it's "unprofessional." Feh. Sometimes you have to break the rules.

If you read the volumes of garbage I've written on this web site, you'll notice that there are a few lame attempts at being funny scattered throughout. Just four paragraphs ago I was making a gross body-fluid joke and making fun of managers for playing golf. Even though I'm not really that funny, I still try pretty hard, and even the act of flailing around trying to be funny is in itself amusing, in a sad-clown sort of way. When you're writing a spec, an easy place to be funny is in the examples. Every time you need to tell a story about how a feature works, instead of saying:
The user types Ctrl+N to create a new Employee table and starts entering the names of the employees.

write something like:
Miss Piggy, poking at the keyboard with a eyeliner stick because her chubby little fingers are too fat to press individual keys, types Ctrl+N to create a new Boyfriend table and types in the single record "Kermit."

If you read a lot of Dave Barry, you'll discover that one of the easiest ways to be funny is to be specific when it's not called for. "Scrappy pugs" are funnier than "dogs." "Miss Piggy" is funnier than "the user". Instead of saying "special interests," say "left-handed avocado farmers."
http://www.joelonsoftware.com/articles/ ... 00033.html

I have tried to make my specs a bit more funny than usual since reading this article

. If I can get Jeff to laugh, I've written a fairly good spec. Hehe.

Joel Spolsky wrote:

Oh, and, by the way, if you think that it's unprofessional to be funny, then I'm sorry, but you just don't have a sense of humor. (Don't deny it. People without senses of humors always deny it. You can't fool me.) And if you work in a company where people will respect you less because your specs are breezy, funny, and enjoyable to read, then go find another company to work for, because life is just too damn short to spend your daylight hours in such a stern and miserable place.

Note to self: Something to keep in mind when I look for a job

.

Joel Spolsky wrote:

Here's why I think that programmers have trouble writing good specs.

When you write code, your primary audience is the compiler. Yeah, I know, people have to read code, too, but it's generally very hard for them. For most programmers it's hard enough to get the code into a state where the compiler reads it and correctly interprets it; worrying about making human-readable code is a luxury... Programmers often try to write specs which look like dense academic papers. They think that a "correct" spec needs to be "technically" correct and then they are off the hook.

The mistake is that when you write a spec, in addition to being correct, it has to be understandable, which, in programming terms, means that it needs to be written so that the human brain can "compile" it. One of the big differences between computers and human brains is that computers are willing to sit there patiently while you define the terms that you want to use later. But humans won't understand what you're talking about unless you motivate it first. Humans don't want to have to decode something, they just want to read it in order and understand it. For humans, you have to provide the big picture and then fill in the details. With computer programs, you start at the top and work your way to the bottom, with full details throughout. A computer doesn't care if your variable names are meaningful. A human brain understands things much better if you can paint a vivid picture in their mind by telling a story, even if it's just a fragment of a story...

I'd never thought about how a more human-readable spec makes it easier to write, and easier to read. When I wrote my first spec, it was really "compiler-friendly". So friendly I didn't know it said, and I gave up and just wrote the software without a spec. As time progressed, and I found I should really consider writing them, I eased off the compileriety (there, just invented a new word) and out came the Bible Dave Design Doc. By the time OFG came around I'd converted to human-friendly docs and haven't looked back since. Jeff would thank me, if he had read my past ones

So there's one of my longest posts ever (by including the quotes). Hope you get something useful out of it, I've already gotten a ton from Joel's thoughts and experience on the subject.

ChristianDevs Forum