Manage Client Expectations

Writing a Specification

Consultant s Corner


Manage Client Expectations

Writing a Specification


By Auri Rahimzadeh


Most independent contractors don t use written specifications. Rather, they tend to begin projects with a dollar estimate and their own understanding of what the project entails, often assuming instead of affirming what the client actually wants. This estimate and unilateral set of assumptions is often based on a series of e-mails and some phone or in-person conversations, and maybe some napkin notes with diagrams. Too often the client is uninvolved, and assumes the contractor knows what they are talking about. This disconnect is the primary reason clients don t get what they were expecting, leading to disputes and collection problems for the contractor.


For many of us, projects are small enough that the specification and the proposal are one and the same, so I ll use the term specification across this article in place of both.


Writing a clear, concise specification and getting the client to sign it is one of the most important steps you can take to ensure not only that the project ships on time, but that it includes exactly what the client requested. Unless you are both on the same page, confusion will lead to scope creep, altered timelines, and an unclear picture of what the client is actually getting and paying for. Written specifications make sure that everyone knows the light at the end of the tunnel is not a train. I live by the credo If it isn t in the spec, it s out of scope. By sticking to this approach, and making sure the client is involved with the spec creation process, nobody has any reason to say they didn t know what they were getting.


A well-written specification is the ultimate in expectation management. Your client should be able to rely on the specification to determine what to expect. You also should be able to tell your client to refer to the specification if they ask why a certain feature is or isn t in the application you ve built. A specification is a written record of the client s expectations, including the limits of what the application will and will not contain.


A well-written specification isn t only a benefit to the customer, it s a savior to you and your development team, as well. If the developers know exactly what to build, you ll get a higher quality application, and they shouldn t be complaining (too much) about what to build.


Some contractors stick to verbal contracts or statements of work. Verbal contracts aren t worth the paper they re written on, and statements of work are usually too brief to describe any project that will take more than a few hours.


There are exceptions to these rules. You won t have a spec for every project, especially small changes or retainers. However, just as a house must always have a blueprint regardless of the changes that are made during its construction, the initial project should always have a specification.


Meet with the Client

Never assume you know what the client wants or needs until you ve met with them. It s arrogant and foolish as a contractor to believe you know your client s business better than they do. Your job as a software architect, development manager, or software developer is to digitize your client s business rules. Listen to them, and make sure you can translate their processes to code.


Avoid Pre-project Scope Creep

Every client I ve met with gets excited once they see the opportunities in digitizing their business rules into a software application. It is at that moment they break out of their original goal and start making pie-in-the-sky requests. It s your job to keep your client focused at this point. Explain that in Version 1 you can do X, then Y in Version 2, and so forth. You also can call these phases. As your client becomes more comfortable with your work, you ll find the request pipe will have a bit more flow control. One way to help organize this pre-project scope creep, and scope creep in general, is with an Issue Management System (IMS) and by assigning those requests to a future project, although a Word or Excel document full of notes can be just as useful. For more on this, see Got Issues?: Improve Communications, Streamline Development with an Issue Management System.


A Good Flow for Your Spec

My specs generally follow the flow defined below. I find it easy for the client to follow if I stick to the same format from one specification to another. I ve considered many changes, such as a table of contents, but the basic flow has stayed the same:

  • Cover Page
  • Executive Summary
  • Graphic Design Treatments
  • Page by Page Functionality (if a Web site)
  • Application Functionality (for both Web sites and Applications)
  • Assumptions
  • Responsibilities
  • Timeline and Milestones
  • Costs and Payments
  • Sign-Off
  • Intellectual Property (IP) and Other Legal Notices


Going into detail in each one of these sections would take up a lot of space, and I think a sample document will explain them better (I ve posted a sample specification for you to view at If you have specific questions, please do not hesitate to e-mail me.


Make Sure It s Clear

Your specification is the be-all and end-all of your application. If a major or minor feature isn t outlined in the spec, it shouldn t be written without a Change Request. Make sure your client understands this. Many consultants like to rely on a one-pager. As I alluded to before, shabby details are why most projects deliver late or over budget, and why you seriously risk not working with that client again. Your client will love you when they see a detailed specification, and they ll appreciate you even more if they peruse a spec from another vendor offering only a project title and a dollar figure.


Be Descriptive Enough

Remember, software development is an art form. You don t need to explain yourself to death. Only document the major and minor features; group related topics together and explain how the business rules are applied to each function. For example:


The User Login screen should explain there will be a Username and Password field, that the fields will be case sensitive, and that the user will be required to enter both fields. Entering a password wrong three times will cause an e-mail to be sent to an administrator at a pre-defined address, and the user will be locked out for a configurable number of minutes, as defined in the Site Configuration screen in the Administration Functionality section of this document.


Note there are no programming details in the preceding explanation it s the business rules applied to a Login Screen, in plain English. Keep programming details out of the document or you ll lose your client, even if they re a programming technorati like you.


It should be understood that you will not necessarily know everything about everything covered in your spec. For example, as a developer, you probably aren t going to make design decisions. That s the designer s job. The specification should not be treated as evidence of your skill set, unless that trade is writing specs; it should clearly outline the goal, the deliverables, and the costs and not get technical unless required. Even when the document needs to be technical, refrain from specifying technologies if you can, because you haven t even started writing the application yet.


Your specification will likely be presented to more than one manager, sometimes one in an executive or CXO capacity. Spelling and, to a lesser extent, grammatical errors can make you look sloppy. If your spec is riddled with errors, think what that says about your promised results! So, as they taught you in high school, re-read your spec and correct it before the first draft is provided to your client. I ve always found it best to write my spec one day, then review it the next after a good night s rest I ll usually find something that needs editing.


Pricing It Out

No matter how great your specification may be, the cost of the project is what you get out of the deal. Estimating your time and assigning a price to it is only one piece of the total project cost. Consider your other costs, such as hardware, software, licensing, certificates, artwork, and even legal fees.


A specification should go through multiple iterations with your client, making sure everything is covered before signing the bottom line. Under no circumstances should you put the dollar amount on the document until you re completely sure the spec is close to getting signed-off. You don t want to sticker-shock the client with your first draft! There will be changes. There are exceptions to this rule, but generally you should keep the price out until the time is right, and you ll know when that is.


Don t ever take a project at a loss just to win the client. Doing so undermines the value of your work and actually sets a cost bar with your client that can be very hard to raise. This isn t a way to get rich off your client, as I warned before, but it s your way of making sure you make money for all your hard work and don t feel cheated if the client doesn t reward you with more projects.


Be realistic about your timeline. When you plan how long things will take, don t count on 40 hours taking only a week consider the amount of time it will take for your client to come back to you with results. So, if you re building a Brochure Ware Web site, it may only be a few pages and take you 20 hours to build. However, the project will actually span a month, because:

  • You start the project
  • You request the Web site content from the client
  • You start and finish design and development
  • You keep waiting for the client to get you site content
  • You finally get the content
  • You place the content and they want to change it a bit
  • The content is finally good to go
  • The client tests the site and has some small changes
  • You make the changes
  • The client says the site is good to go
  • You determine who to use for hosting
  • The client finally agrees with the hosting costs
  • You publish the site


Look at that: The 20 hours of development pales in comparison to the rest of the process! Had you told your client it would take one week to get their site done, you d be three weeks behind; sure, it would be their fault, but you d get blamed! So, when you write that timeline, think about the entire process and price it accordingly. There s an extra 10 hours or so of time beyond design and development time in what I described above make sure that s part of your estimate.


You ll notice I charged for client communication time. Some contractors I ve worked with don t charge for this time; others do. It s a fine line; you don t charge for every client communication, especially if you briefly called or e-mailed the client. However, if you need to meet with the client regarding their project, that should be billable time. You re a contractor; you make money by selling your time don t sell yourself short!


When pricing things out you also should consider contingency time, which is just in case cost. Often, your client will want to make some changes, and you can predict these such as adding a couple more pages to the site or last-minute image changes. Your own tasks also may take longer than what you originally planned. Instead of going through the whole invoice-approval process all over again, it s best to add contingency hours to the project (usually 10% to 30% over your original estimate).

Lastly, make sure you break out each cost in your project, as well as prominently display the final cost. Show the client how much the SSL certificate is likely to cost, and how much any third-party software will cost. Don t simply roll it up into a total price, or it may not be clear that you can t control certain costs in the project.


Mitigating Sticker Shock

Just as when you look at a price tag and wonder why something seems to cost more than it should, your client is going to do the same. As a contractor, you should be honest about your price don t inflate it just so you can negotiate down. But how can you help your client accept the price if they re not sure they can afford it?


What I described above, where the cost is all-inclusive, is called a fixed-bid proposal. There are two other types: T&M and not-to-exceed.


In T&M (or time and materials ), you allot the total number of hours and the individually priced line items, such as SSL certificates, and your client pays a fixed hourly rate as defined in the proposal. Their gamble there is that you may finish the work ahead of schedule, and thus they ll pay less for your time. Unfortunately, T&M is a very risky venture for your client, because they ll usually have extra requests that your fixed-bid price would have included, but instead they must pay hourly. At often over $100/hour, costs add up pretty quickly.


The compromise to this is a not-to-exceed proposal, which basically means you are quoting the total number of hours you originally estimated, plus the line items, and you ll work up to that total number of hours. This is a good way to get the client to accept the price, and let them take the gamble of T&M, while recognizing there s a ceiling. It doesn t necessarily promise the project will get done within the original fixed-bid budget, but it should if your original estimates were correct.


Get Paid Up Front, and Break Out Large Project Payments

Before you start a project, you should get paid some percentage of the project up front. You have project start-up costs, and your client shouldn t ask you to perform work without giving you something to work with. For new clients, I usually ask for half the project cost up front. This, of course, depends on the size of the project. If it s a $100,000 project, I ll ask for 25% up front, then have milestone payments in the timeline and listed on the project cost page of the specification. As I reach each goal, I should be paid by the client, no questions asked. Your client will appreciate the milestone payments it makes it much easier for them to get approval if they don t have to pay large amounts all at once.


Make sure that on your costs page you put a line that states all invoices are authorized. Your client should take the responsibility for making sure you get paid, and shouldn t complain that they don t have the money after they ve asked you to do the work.


Try to Own the IP

A touchy subject for contactors and their clients is who owns the code. Technically, everything you do may be considered work made for hire, which means your code would belong to the client in exchange for your compensation. There s a gotcha here: often you will re-use code you ve used across many projects. So who owns the code in that case? If you re using any existing code, your proposal should explain, at a bare minimum, that no rights to that code are transferred to your client. They should be allowed a license to use the application, but should retain no rights to transfer that license. This is where having an attorney comes in handy. I ve said this before, but it bears repeating: a qualified IP attorney is one of the basic resources for a software business. For some tips on attorneys and other resources you should have available to you, see my article Starting Your Business: The Legal Stuff.


Make Sure the Client Signs It!

Don t take your client s word that they agree to the specification s contents if they won t sign it. Always get them to sign off on your spec before any work commences. Otherwise, you ve left the scope, the payment terms, the intellectual property control, and more all in the dust, and you have no mutual understanding of expectations.


Writing a clear specification is an art, but it will greatly increase the likelihood that your project will ship on time and meet the client s expectations. That same document will keep you on the same page as your client, and make sure you don t stray off course or deliver late.


If you have any questions or feedback, please e-mail me at [email protected]!


Auri Rahimzadeh is President and Senior Engineer at TAG (The Auri Group, LLC,, a Microsoft Gold Certified Partner based in Indianapolis, IN. Rahimzadeh has authored three books, including Hacking the PSP and Geek My Ride. He has been technical editor on Wrox and Wiley titles, and has written a number of technical articles ranging from .NET development to consumer electronics. Auri started his technology career working for Steve Wozniak, co-founder of Apple Computer, and enjoys writing and teaching others about all sorts of technology.




Hide comments


  • Allowed HTML tags: <em> <strong> <blockquote> <br> <p>

Plain text

  • No HTML tags allowed.
  • Web page addresses and e-mail addresses turn into links automatically.
  • Lines and paragraphs break automatically.