Fog Creek Software
Discussion Board




Functional vs Technical Spec

Hi Joel,

I am in the process of writing a functional spec for a new product. I really enjoyed your articles from a few years back on the functional spec process. In the beginning of one of the articles you define the difference between and functional and technical spec. I am curious if you have written anything that describes taking a functional spec and turning it into a technical spec?

Thanks for the great site.

Kevin

Kevin Moore
Monday, March 22, 2004

I haven't written such a thing.

My way of thinking is that you just don't write "technical specs" that cover the entire functionality of an application ... that's what the functional spec is for. Once you have a complete functional spec the only thing left to document is points of internal architecture and specific algorithms that are (a) entirely invisible (under the covers) and (b) not obvious enough from the functional spec.

So the technical spec winds up not existing. In it's place you may or may not have a few technical articles on small topics:

http://www.joelonsoftware.com/articles/CityDeskEntityClasses.html

is a nice example of such a thing.

Remember, if anything you're talking about affects the user interface or even the behavior of the thing you're building, it goes in the functional spec... so all that's left for technical specification is things that are SOLELY of interests to programmers, and, in fact, a lot of that stuff might be best in comments, so at most, you should have a handful of short articles on topics like algorithms -- and you write those articles on demand, when you need to think through a design, or document the "big picture" for future programmers so they don't have to figure out what your code is trying to accomplish.

Joel Spolsky
Fog Creek Software
Tuesday, March 23, 2004

>http://www.joelonsoftware.com/articles/CityDeskEntityClasses.html

Wow! Elegant code.

Sathyaish Chakravarthy
Tuesday, March 23, 2004

So Joel, how do you get the identity of the tuple you just inserted?  Is the auto-number in your code?

i like i
Tuesday, March 23, 2004

I find that I don't tend to write a be-all and end-all tech spec, because I'm usually the one coding it. I make an effort to code clearly and more useful points (like an API) wind up in a sort of technical summary.

The appropriate level of documentation can vary from project to project, of course. From just the functional spec side, Alistair Cockburn's Effective Use Cases goes into depth on what your documentation should cover. (only get a copy of you're *really* into that sort of thing though)

Joel Goodwin
Tuesday, March 23, 2004

The ID of a "saved" row is always returned, regardless whether "Save" performed an insert or an update.

Oh, and if your programmers aren't smart enough to work from a functional specification plus a few articles as Joel suggested, aside from firing them you could define interfaces (i.e. classes containing only pure virtual members) and document those.  In the C# world, this is dead easy, especially if you use the code documentation features, which allow you to write something like:

namespace Oli.DataAccessLayer {
    /// <summary>The IEntity interface will be implemented
    /// by all classes in the Data Access Layer
    /// <seealso href="joelonsoftware.com" />
    /// </summary>
    /// <remarks>
    /// Idea stolen from Joel's article on
    /// Entity classes.
    /// </remarks>
    public interface IEntity {
        /// <summary>
        /// Every entity can at least be
        /// loaded.
        /// </summary>
        /// <param name="id">The ID of the
        /// entity to load</param>
        public void Load ( int id );
    }
}

Oli
Tuesday, March 23, 2004

Oops, I forgot to point out that NDoc, an open-source tool, will turn the XML comments you sprinkle in your .NET code into Javadoc-style HTML pages, CHM-style documentation or even the newer MSHelp 2.0, so that your code documentation looks just like Microsoft's.

Oli
Tuesday, March 23, 2004

For those who are interested, what Joel describes is pretty much verbatim what Martin Fowler calls a Row Data Gateway.

Martin's book "Patterns of Enterprise Application Architecture" is packed full of great information on designing applications. While it's not necessarily a book for all developers, anybody who's in a high level design position will probably get a lot of value out of it (plus the Gang of Four "Design Patterns" book).

Brad Wilson (dotnetguy.techieswithcats.com)
Tuesday, March 23, 2004

*  Recent Topics

*  Fog Creek Home