Joel on Software
Painless Functional Specifications - Part 4: Tips
by Joel Spolsky Sunday, October 15, 2000
OK, we've talked about why you need a spec, what a spec has in it, andwho should write them. In this fourth and final part of the series I'll share some of my advice for writing good specs.
好，我们已经讨论了：为什么需要规范； 规范包含什么内容； 以及谁应该编写规范。 在这些列的第四部分同时也是最后一部分我将和大家分享写好规范的建议。
The biggest complaint you'll hear from teams that do write specs is that "nobody reads them." When nobody reads specs, the people who write them tend to get a little bit cynical. It's like the old Dilbert cartoon in which engineers use stacks of 4-inch thick specs to build extensions to their cubicles. At your typical big, bureaucratic company, everybody spends months and months writing boring specs. Once the spec is done, it goes up on the shelf, never to be taken down again, and the product is implemented from scratch without any regard to what the spec said, because nobody read the spec, because it was so dang mind-numbing. The very process of writing the spec might have been a good exercise, because it forced everyone, at least, to think over the issues. But the fact that the spec was shelved (unread and unloved) when it was completed makes people feel like it was all a bunch of work for naught.
你从那些真正在编写规范的团队听到的最大抱怨就是“没有人会读规范”。如果没有人阅读规范，那么写规范的人就会有点儿愤世嫉俗。就像迪尔伯特漫画里描绘的那样，工程师们使用一摞摞4英寸厚的规范来扩展他们的工作隔间。在那些一般大的，官僚作风的典型公司，每个人都会花数月来编写无聊的规范。规范一写完就会被放到架子上去，再也不会被拿下来，而产品则是从头做起绝不会参照任何规范的描述，因为没有人阅读规范，因为规范是如此的让人头皮发麻（无聊，愚蠢）。编写规范的过程也许是个很好的训练，因为它让每个人至少去仔细思考这些问题，但是规范完成后就被高高搁置（没人爱也没人读）让人觉得写规范就是件徒劳无功的工作。
Also, if your spec never gets read, you get a lot of arguments when the finished product is delivered. Somebody (management, marketing, or a customer) says: "wait a minute! You promised me that there would be a Clam Steamer! Where's the clam steamer?" And the programmers say, "no, actually, if you look on the spec on chapter 3, subchapter 4, paragraph 2.3.0.1, you'll see it says quite explicitly 'no clam steamer.'" But that doesn't satisfy the customer, who is always right, so the grumpy programmers have to go retrofit a clam steamer into the thing (making them even more cynical about specs). Or a manager says, "hey, all the wording on this dialog is too verbose, and there should be an advertisement at the top of every dialog box." And the programmers say, in frustration, "but you approved the spec whichprecisely listed the layout and contents of every dialog box!" But of course, the manager hadn't actually read the spec, because when he tried, his brain started seeping out through his eye sockets, and anyway, it was interfering with his Tuesday golf game.
同时，如果你的规范从来没被阅读过，当你的产品完成并交付的时候你就会遇到很多争端。有人（管理层，销售，或者顾客）就会说：“等等！你答应过我会做个满汉全席的 ！满汉全席在哪儿？”然后程序员就会说，“不，实际上，如果你看看规范第三章第4小节，2.3.0.1段，你就会很清楚的看到写着‘没有满汉全席’”。不过这不会让客户满意，因客户永远是对的，所以暴躁的程序员只好去产品里改造出个满汉全席来（这就让规范存在的意义显得更讽刺了）。或者经理会说，“嘿，这个对话框上的文字太冗余了，而且每个对话框的顶部都应该要个广告。”然后程序员就会很沮丧的说，“但你已经批准了这个规范，规范上准确无误的描述了每个对话框的布局和内容。”但是，经理实际上当然没有去读那个规范，因为他刚要尝试,他的思绪就透过他的眼睛飘了出去，再说，这打扰了他礼拜二的高尔夫球赛。
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." Instead of saying "People who refuse to clean up after their dogs should be punished," say that they should be "sent to prisons so lonely that the inmates have to pay spiders for sex."
如果你读过很多Dave Barry的著作，你就会发现幽默最简单的方式就是在不需要的时候特定点。“旺财”比“狗”幽默。“胖小姐”比“用户”幽默。与其说“特殊爱好”，不如说“左撇子梨树老农”。 与其说“在他们的狗做了应该被惩罚的事之后人们不愿意打扫”不如说“他们应该被关进那种监狱，在那里，囚犯们太寂寞甚至要付钱跟蜘蛛乱搞。”。
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 gofind another company to work for, because life is just too damn shortto spend your daylight hours in such a stern and miserable place.
哦，另外，顺便说一下，如果你觉得幽默是那么不专业的话，那么我很抱歉，你就是没有幽默感（别否认，没有幽默感的人总是抵赖，你骗不了我。）另外，如果你工作的公司因为你写的规范轻松活泼，幽默，令人读来十分愉悦而不尊重你的话，另外找个公司工作吧，因为把你的宝贵白天时间花费在这么个严厉而可悲的地方简直都能让人折寿。
Rule 2: Writing a spec is like writing code for a brain to execute
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. Whether you write:
当你写代码的时候，你的主要对象是编译器。是的，我知道，人也得会阅读代码，但总体来说对他们很难。对大多数程序员来说让编译器正确理解他们的代码已经足够困难了；操心要写出人类可读的代码实在太奢侈了。当你写出：
void print_count( FILE* a, char * b, int c ){
fprintf(a, "there are %d %s\n", c, b);}
main(){ int n; n =
10; print_count(stdout, "employees", n) /* code deliberately obfuscated 代码被故意混淆过了 */ }
or 或是
printf("there are 10 employees\n");
you get the same output. Which is why, if you think about it, you tend to get programmers who write things like:
得到的输出都是一样的。如果你仔细想想，这也就是为什么，你更倾向于要雇佣能写出这样的东西的程序员:
Assume a function AddressOf(x) which is defined as the mapping from a user x, to the RFC-822 compliant email address of that user, an ANSI string. Let us assume user A and user B, where A wants to send an email to user B. So user A initiates a new message using any (but not all) of the techniques defined elsewhere, and types AddressOf(B) in the To: editbox.
假定一个函数 AddressOf(x) 定义了从一个用户x到该用户的符合RFC-822标准规定的email地址映射ANSI字符串，假定用户A和用户B，用户A想要给用户B发送电子邮件。所以用户A采用其他任意定义的技术（但不是所有）起草了一个新的信息，并在“发送到”编辑框内输入了AddressOf（B）。
This could also have been speced as:
这段规范也可以这样描述：
Miss Piggy wants to go to lunch, so she starts a new email and types Kermit's address in the "To:" box.
肥肥小姐想要去吃午饭，所以她就起草了封新邮件并且把Kermit的地址输入到了 “发送到”地址框内。
Technical note: the address must be a standard Internet address (RFC-822 compliant.)
技术提示：地址必须是标准因特网地址（符合RFC-822规范）。
They both "mean" the same thing, theoretically, except that the first example is impossible to understand unless you carefully decode it, and the second example is easy to understand. 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, because our brains have evolved to understand stories.
错误在于当你编写规范的时候，除了要正确，它必须是能被理解的，用编程术语来讲就是说，它应该写成人脑能正确编译的那样。人脑和电脑最大的差别之一就在于：当你在定义以后要用的术语的时候，电脑能安静的在旁耐心等待。而人脑如果你不激励它，它根本就不能理解你在讲什么。人类不会想要去“解码”什么东西，他们只想顺序阅读然后能理解它。对人而言，你必须先提供宏观的描述然后再描绘细节。用电脑程序，你能够从最顶层开始一直工作到最底层的全部细节。电脑不管你的变量名是否有意义。而人脑如果你能够通过讲故事，哪怕是一小片段，在它们的脑海中描绘一幅栩栩如生的图画，那么人脑理解起来就容易多了。因为我们的大脑参与了进来，来理解故事。
If you show a chess board, in the middle of a real game of chess, to an experienced chess player for even a second or two, they will instantly be able to memorize the position of every piece. But if you move around a couple of pieces in nonsensical ways that couldn't happen in normal play (for example, put some pawns on the first row, or put both black bishops on black squares), it becomes much, much harder for them to memorize the board. This is different from the way computers think. A computer program that could memorize a chess board could memorize both possible and impossible layouts with equal ease. The way the human brain works is not random access; pathways tend to be strengthened in our brains and some things are just easier to understand than other things because they are more common.
如果你向一个经验丰富的棋手展示一幅进行中的真实棋盘，哪怕只有一两秒，他们马上能够记起每个棋子的位置。但如果你用正常比赛中不会出现的非理性方式走两步棋（例如，在第一排布两个卒，或者把两个相都放在黑格子中 ），要让他们再记住棋盘就困难多了。这跟计算机的记忆方式是不一样的。计算机程序要记忆可能和不可能的布局是一样容易的。而人脑的工作方式并不是随机访问；过程更容易在我们大脑中得到加强，而有些东西就是比其他东西更容易记忆。 因为它们更加正常。
So, when you're writing a spec, try to imagine the person you are addressing it to, and try to imagine what you're asking them to understand at every step. Sentence by sentence, ask yourself if the person reading this sentence will understand it at a deep level, in the context of what you've already told them. If some members of your target audience don't know what RFC-822 is, you either have to define it, or, at the very least, bury the mention of RFC-822 in a technical note, so that the executive-types who read the spec won't give up and stop reading the first time they see a lot of technical jargon.
所以，当你在编写规范的时候，尝试想象你正在给其陈述的对象，尝试去想象每一步你要让他们理解些什么。一句一句地，问问你自己，在你已经阐述的上下文中，如果别人读到这个句子能否深层次的理解它。如果你的受众群体的一些人并不知道什么是RFC-822，你要么得定义它，或者至少在技术提示里提一下RFC-822，这样那些执行董事们在阅读你的规范的时候不会一看到技术术语就放弃然后停止阅读。
Rule 3: Write as simply as possible
Don't use stilted, formal language because you think it's unprofessional to write in simple sentences. Use the simplest language you can.
不要因为你觉得用简单的句子显得不专业就用做作的正式语言。使用你能使用的最简单语言。
People use words like "utilize" because they think that "use" looks unprofessional. (There's that word "unprofessional" again. Any time somebody tells you that you shouldn't do something because it's "unprofessional," you know that they've run out of real arguments.) In fact I think that many people think that clear writing means that something is wrong.
人们会因为“采用”显得不专业而使用诸如“选取”这样的词语。（又出现了“不专业”这个词。每当有人告诉你因为那不专业而不要做某件事情的时候，你就应该意识到他们其实没什么真实的论据。）实际上我认为很多人觉得清楚的写作意味着什么东西出错了。
Break things down to short sentences. If you're having trouble writing a sentence clearly, break it into two or three shorter sentences.
把长句打断成短句。如果你不能清楚的写出一个句子，那么就把它改成两个或三个更短的句子。
Avoid walls of text: entire pages with just text. People get scared and don't read them. When was the last time you noticed a popular magazine or newspaper with entire pages of text? Magazines will go so far as to take a quote from the article and print it, in the middle of the page, in a giant font, just to avoid the appearance of a full page of text. Use numbered or bulleted lists, pictures, charts, tables, and lots of whitespace so that the reading "looks" fluffier.
避免满满的一面都是文字：一整页只有文字。人们会感到害怕然后不去读它们。你上次看到报纸或杂志满满的一页都是文字是什么时候？杂志通常会在页面中间这里从文章中摘一个句子然后用巨大的文字印在这里，仅仅为了避免这一页看起来满满的都是文字。 __
"Magazines will go so far as to take a quote from the article and print it, in the middle of the page, in a giant font, just to avoid the appearance of a full page of text."
杂志会在页面中间这里从文章摘一个句子然后用巨大的字体印在这里，仅仅为了避免这一页看起来满满的都是文字。__
Nothing improves a spec more than lots and lots of screenshots. A picture can be worth a thousand words. Anyone who writes specs for Windows software should invest in a copy of Visual Basic, and learn to use it at least well enough to create mockups of the screens. (For the Mac, use REAL Basic; for Web pages, use Front Page or Dreamweaver). Then capture these screenshots (Ctrl+PrtSc) and paste them into your spec.
没有什么能够比大批大批的截图更能改进规范了。 一张图胜过一千句话。任何为Windows软件写规范的人都应该投资买一份VisualBasic，然后至少要学会用它来创建屏幕模型。（Mac用户请使用RealBasic；网页开发请使用FrontPage或Dreamwaver）。然后捕捉截屏（Ctrl+PrtSc）并把它们粘贴进你的规范。
Rule 4: Review and reread several times
Um, well, I was originally planning to have a lengthy exegesis of this rule here, but this rule is just too simple and obvious. Review and reread your spec several times, OK? When you find a sentence that isn't super easy to understand, rewrite it.
嗯，很好我本打算在这里对这条规则写上冗长的解释，但这条原则是在太简单太明显了。多评审和阅读几次，好吗？当你觉得有个句子读起来不是那么简单易懂的时候，重写吧。
I've saved so much time by not explaining Rule 4 that I'm going to add another rule.
不解释第四条原则帮我节省了这么多的时间，我决定再加一个原则。
Rule 5: Templates considered harmful
Avoid the temptation to make a standard template for specs. At first you might just think that it's important that "every spec look the same." Hint: it's not. What difference does it make? Does every book on your bookshelf at home look exactly the same? Would you want them to?
避免为规范制作标准模板的冲动。一开始你可能觉得“所有的模板都有一种一致性”看起来很重要。提示：不是这样的。这样有什么好处呢？你家里书架上的书看起来都一样么？你希望它们一样么？
Worse, if you have templates, what tends to happen is that you add a bunch of sections to the template for things that you think are important for every feature. Example: Big Bill decrees that from here on forward, every Microsquish product shall have an Internet component. So the spec template now has a section that says "Internet Component." Whenever somebody writes a spec, no matter how trivial, they have to fill in that section that says "Internet Component", even if they're just creating the spec for the Microsquish Keyboard. (And you wondered why those useless Internet shopping buttons started cropping up like mushrooms on keyboards).
更糟的是，如果你有模板，通常会发生的事情是：你会为你觉得对每个特性都很重要的地方都添加一个部分。例如：大比尔法令规定，从今往后，所有Microsquish产品都必须有因特网部件。因此现在所有的规范模板都有一个叫做“因特网部件”的部分。不管谁写规范，不管多么简单，他们都必须去填写那个叫做“因特网部件”的部分，哪怕他们只是要为Microsquish键盘编写一个规范。（你很诧异为什么那些因特网购物按钮开始像蘑菇一样从键盘上冒出来）。
As these sections accumulate, the template gets pretty large. (Here is an example of a very, very bad template for specifications. Who needs a bibliography in a spec, for heaven's sake? Or a glossary?) The trouble with such a large template is that it scares people away from writing specs because it looks like such a daunting task.
随着这些部分的积累，模板就会越来越大。（这儿有个非常非常糟的规范模板。天呐，谁会想要在规范里写个自传？还有一个词汇表？）这么大的规范模板的问题在于：它会把编写规范的人吓跑，因为人们会觉得这是多么恐怖的一件事情啊。
A spec is a document that you want people to read. In that way, it is no different than an essay in The New Yorker or a college paper. Have you ever heard of a professor passing out templates for students to write their college papers? Have you ever read two good essays that could be fit into a template? Just drop the idea.
规范是你希望人们去读的文档。这样它就跟《纽约客》上的散文或是校报上的散文没有区别了。你听说过教授分发模板让学生们在校报上写文章的么？你读到过俩篇好文章能塞进一个模板的么？放弃这个念头吧。