I enjoyed Joel's articles on functional specs, but my team is beginning work on the tech specs... anyone have a great example of, or ideas on technical specs?

-- Anonymous, November 03, 2000

Answers

I also like Joel's writing about functional specs. I was at the end of a web project that didn't have one. I'm curious about a way to do quick spec for small web applications and even web site navigation.

Joel's example using Kermit and Miss Piggy reminded me of the importance of humor (or something interesting) so I added some humorous quotes to my writing. I was not sure how international Kermit and Miss Piggy were, and I need to write for an international audience. I figured that quotes were obviously something a non- English reader could skip over.

-- Anonymous, November 03, 2000

Specs are generally for internal consumption so it's easier to judge what will work and what won't. In the case of user manuals where they will be widely distributed you have to be more careful. Even in the English-speaking world, the Brits have a different sense of humor than North Americans. Humor that is based on language subtleties(like puns) or on culture (your favorite tv show) are not going to travel well.

Humor that is based on offbeat examples seems to work pretty well with everyone.

-- Anonymous, November 04, 2000

Use pictures!....

See the subj above

-- Anonymous, November 04, 2000

I Agree, use pictures!!!, A few years ago, when I was in a junior management position one of my programmers was tasked with maintaining a bizarre (to say the least) legacy system. He was up to his eyeballs in confusion, so I told him to 'draw the system', with lots of colours ;). He did & worked it out! It's true, a picture is worth a thousand words. But then again, that's probably why UML type tools are gathering momentum ;). BTW Has anyone 'really' used togethersoft (www.togethersoft.com of peter coad fame) on a project? We were evaluating it until we figured that modifying it to create the EJB's the way we wanted was going to be pretty tricky. (don't ask me to explain, this is still political ;)

-- Anonymous, November 05, 2000

Re: Together/J. We use it to great effect. I've been using it, to a greater or lesser extent, for about two years or so. My current team *does not* use it to create our EJBs (that's using a "wizard" and "wizards" lead to developers that don't know much). We *do* use it to visualize and refactor code. It has spread like a virus on my team - when people saw me using it, they'd say "what's that, can I get it?". This never happened with Rose. After doing lots of framework development using T/J I can say it's pretty much a lifesaver when a major refactoring is in order. Its documentation features are great, too. I'm pretty much a zealot (though I still use 'vi' for quickie changes :-)).

-- Anonymous, December 03, 2000

If your project involves a Web-site (be honest now, which project doesn't!) then I find "working mockups" to be a great specification tool. Sure they take a couple of days to build, but the actual clicking, jumping from page to page etc. seems to bring up creative juices in "pointy haired types". It is much better to do this early in the game via an easily modified mockup rather than a completed web- site. Note that a critical component of the mockups is the ability to access hyperlinks to go to a new page, click buttons to submit a form and receive a result etc.

If it is a desktop app, then Joel's suggestion of using VB to build a prototype is a great way to to.

-- Anonymous, April 10, 2001

Visio has a template for building web-site diagrams, I've used it, but find it doesn't do what I'd really like it to.

I agree that a mock up is a great way to do it... and it's usually something that you can give to your graphics department (if you have one) so that your developers can continue working on the development stuff.

I've also seen it done with UML sequence diagrams and/or collaboration diagrams. When my architect colleague was trying to work out how an existing system of ours was pieced together. Useful for those "dynamic" pages that could end up doing anything. The sequence diagrams worked really well for the frame based layout our site had.

Has anyone thought of writing a decent tool to do this kind of thing? What would be required, etc?

-- Anonymous, July 25, 2001