Are there standard practices when writing a spec for a software development project

Did you read part 2 of the article or his sample specification? They embody a couple important principles when writing a specification.

• Don't overdesign. The purpose of writing the spec is to force you to think about important things like what happens when there's an error, and how you expect the user to interact with the system. You don't have to go into inordinate detail to get something you can work from. You do need details, though.
• It's about communication. The purpose of the spec is to come to a common agreement about what needs to be done. It's not an ironclad document that requires the force of law. It's a tool to help you better understand your client, and your client to better understand what you want to do for them.

The best advice is to write enough so that you are clear on what you need to do. If you have open questions, document them in the spec and get answers from your client. Once you adequately understand what's needed stop.

If you are not careful, the document will take on a life of its own. It should have one purpose, don't add anything to the document that doesn't fit that purpose. It should be easy to maintain. If you have your entire detailed class diagrams in there along with other details that really belong in a unit test, you will either abandon the document because the upkeep is too much, or you will never get the project completed.

About Writing

Writing for people is hard. In fact, the two hardest things about writing is knowing how to start, and knowing when to stop. In the beginning you just have to do something. My advice for dealing with these two hardest aspects is:

• Know your audience. Who is supposed to read the spec? If it's just you and the client, then that's who you are writing to. If you have someone responsible for testing, you'll have some notes for them as well.
• Start with the highest priority thing. While authentication is important, the login screen is probably the best understood piece most folks have to write. Instead focus on that feature that your users need most. You know, that part that makes them money and is the whole reason they need the software.
• Fill in details as the questions come up and you get answers. Keep things really simple with napkin drawings if necessary until the client is happy with the arrangement. It's important to know what information is involved and how they will use it.
• Stop when adding more doesn't add value. There are some details you just don't want in a spec. You need to know when you have the right thing. You don't need to know that there is a variable inside a method named "albaquerque". That's source code, not specification stuff.

Recovering from the "hero coder" mentality is huge as the company grows. Many small companies want low overhead and don't want a lot of process. They can often achieve a lot very quickly from scratch with few people. Marketing makes crazy promises to customers because they have to and developers pull off feats of hacked-out brilliance at the last minute to save the company.

But then legacy costs and technical debt catch up as the company becomes more entrenched in their market. Progress becomes slower. Much slower. The code is abysmal. The developers are burnt out all the time and bitter. Promises made to customers stop being met. People play the blame game.

Transitioning out of the knee-jerk, fire-fighting, expecting feats of brilliance culture to one that maintains some semblance of sanity and planning can be a difficult and painful culture shock for small companies.

They say the fast beat the slow but eventually you're worn out from going so fast that you become slower then the slow. Everyone knows the tortoise ultimately beat the hare :)