Fog Creek Software
Discussion Board

The language of functional specs

Hello, Joel,
        I speak French, Spanish, and Portuguese fluently, and used to speak Hebrew and Arabic fairly, but could never bring myself to become fluent in business or tech jargon. 

      Your article on the way functional specs should be written really made me enthusiastic.  Finally - someone else who likes  to speak English in a technical setting!

    Chapter 8 of  Talking Power by linguist Robin Lakoff (professor and, I believe, mentor of best-selling author and linguist Deborah Tannen) addresses the same issue in the setting of academe.  It drives me crazy when people deliberately use language to prevent comprehension while pretending they are trying to bring it about. 

    I’ve quickly read a couple of other articles - why programmers should not report to program managers, about compensation, etc.  I like the way you thinnk!

Robin S.

Robin Schoener
Thursday, March 20, 2003

" It drives me crazy when people deliberately use language to prevent comprehension while pretending they are trying to bring it about.  "

Most research papers I read are this way, and the funny thing is one of my profs (this guy is one of the guru's of Data Mining - his paper was the basis for Sergey & Larry's course in Stanford) - jokingly/ seriously said that it is done on purpose - to make it look like it has more substance than it really does.

It is one of those things with academia...Sigh!

Prakash S
Thursday, March 20, 2003

A counterpoint to that: while most of a spec I recently wrote was pretty clear, I had a few things where the wording was rather awkward in an attempt to be exactly correct.

My copy of Knuth's TAOCP lapses into this a lot. Much of it is fairly readable (given how much he's covering, at least), but the definitions and math are dense. Sure, they mean exactly and only what is intended, and no other interpretation is possible... but it's still dense as a brick wall 8-}

Mike Swieton
Thursday, March 20, 2003

This shows why technical writing is *hard*.

Brent P. Newhall
Thursday, March 20, 2003

Before writing his doctoral thesis, Isaac Asimov wrote a fake research paper about a fictional substance that would disolve before the solvent even touch it.

He felt that after a few years trying to write well, he needed some practice on the bad writing required in academia. By the way, it is very funny

Friday, March 21, 2003

Language in specialised areas is often unitelligable to the outsider precisely because it tries to be more clear to the specialist. We make disctictions between HTML jockeys, scripters, programmers, analysts, architects, DBA, administrators, testers, hardware engineers .... while the rest of the world just gives us a blank look talks about "yeah, guys that do computers".
The same thing holds for academic subjects.

It is true however that sometimes in academia language is used for devious obfuscation. This is often not even targetted to the layman, but mostly to the peer group. Very weak and unsubstantial models are served up in inpenetrable formalizations. This sadly works because no reviewer has the time to eat his way through the cloth, and so the work gets accepted, published and forgotten, it's only contribution being that of bulking up the publication record of the author.

A second case where I have often met this is to rehash an old subject once more. Rename all the concepts and relations in the models, and suddenly everything old is new again. The main target of this is the funding agencies.
"We can't get money for Good Old Fashioned AI, since someone else has already done it 20 years ago and limitations of this approach have been exposed by others. Hmmm ... let's call it the Semantic Web then ..."

Just me (Sir to you)
Friday, March 21, 2003

For truly obfuscated language, here's a guide:

Deepak Shenoy
Friday, March 21, 2003

*  Recent Topics

*  Fog Creek Home