Tips for a Better Functional Design Document

When I started consulting in 1997, I started out as a developer. My job was to develop code from Functional Design Documents (FDD) that onsite functional consultants wrote. Usually the first step, was to have long conversations with these consultants on what the client was expecting for end-results, because it was not clear in the FDD. Many-times, what was written contained limited information and was confusing as to what the customer really wanted.  After a couple of years, I started to write my own FDD's when I started to be more customer facing and I began to work with clients directly.  I quickly found that writing an FDD was not as easy as I thought. My first several FDD's got me into some trouble where I was having to give some of my time for free because I left out some details. I quickly started to adjust the way I wrote FDD’s so that it was very clear what needed to be coded and how it worked. Once I figured out how to write a good FDD the complaints from the customer and giving away hours basically went away.

When I moved into management, I started to see other's design documents and the nightmare of my earlier experiences with FDDs quickly came to mind. I remember I had one customer that kept complaining about a certain customization. I had a couple of functional resource work on the design and rework the design, with different developers working on the solution. No matter who I put on the FDD, I could not get the customer to sign-off on the delivery of the FDD. I took ownership of the FDD and scheduled a call with the customer. We went through the FDD and the desired result. After a few calls and few re-writes, we finally got to a point where I asked the customer to physically sign the FDD, which stated they agree to the changes. At that point, the customer brought up additional scenarios. Urgh… the frustration! We added the additional scenarios and then the customer agreed to sign the document. I handed the FDD over to the development team. The developer called and delivered the first round of the customization. I went through the test scripts that were part of the FDD and the first test failed. Another frustrating event. I asked the developer if he went through the test scripts. After a short communication dance, he admitted he did not go through the test scripts. Once I convinced him he needed to go through the test scripts as part of his testing, he delivered a solid customization. I was able to deliver the customization to the customer without any bugs or issues. 

Since that incident with me taking ownership of the FDD, I insisted my team to send all the FDDs to me for verification before we send it to the development team.  Over the years, I have reviewed several hundred FDDs. I have seen great FDDs and I have seen documents that claim to be FDDs but were far from an FDD. I have seen FDDs written by junior consultant, senior consultants, and from Solution Architects and I can tell you that it does not matter the title, most consultants do not know how to write FDDs that will produce clean and useable code the first go around, but I am here to share with you some of my top tips for a great FDD. My first tip is that before you start writing the FDD, you should get approval. FDDs are created because a gap on the requirements needs to be filled. Before we spend hours or even days writing and rewriting an FDD, you should run the cost and effort by the client's decision makers. If you do not and you could spend 3 days writing a very nice FDD, then find out the client does not want to spend the dollars or the time to have it developed. Basically, you just wasted 3 days’ worth of work. Instead, write-up a brief description or paragraph without all the details that you can send to the client quick approval.

Breadbox vs Mansion This short write-up can also be used to explain to a developer, so they can tell you if it is a breadbox or a mansion type effort. Breadbox being a small development project as compared to a mansion that has many levels and complexities you may not have thought of. Here is what should be included in the write-up:

a) Change Request Number – used to track the change request for the project. Rejected or accepted, we track it.

b) Overview – This is a brief paragraph of the change request.

c) Business Justification – The business needs to evaluate if they can live without the change or if it’s critical for the business to operate.

d) High-level Estimate (HLE) – This should be a T-shirt size, never given in hours. Example might be Small, Medium, Large, Extra-large. Your company might have these defined in a range of hours. The customer will remember hours, so best practice at this stage is to use T-shirt size. Once the details and scenarios are flushed out in the actual FDD, then the developer can provide a more accurate estimate.

FDDs are a form of communication. Having exceptional communication skills is critical to be a top consultant. The quality and frequency of communication on a project is in direct relation to the overall the success. The following are my top tips for consultants to create better FDDs:

1.     Know your audience: The FDD is not just for the consultant and the developer. The FDD will be used by several groups:

a) Customer's Decision Maker/Steering Committee

b) Project Team (Customer or partner)

c) Developers

d. Quality Assurance/Testers

e) Support Team (yes, this team will review the FDD at some point)

f) End Users/Subject Matter Experts

g) The upgrade team

2.     The FDD parts: The following are sections that should be in an FDD.

a) Change Request Number – use the same number from the original HLE write-up. Keep tracked with the project.

b) Title – a single line that is descriptive enough to know what area of the system has the change.

c) Overview – Descriptive paragraph of the change; be brief.

d) Business Justification - Why does the business need this change.

e) Scope – a list of the areas that need change or created. This is just a list for example: Sales Parameter, Sales Order Entry, Sale Order Invoice. This list should be numbered in correspondent to the descriptive change area.

f) Out-of-Scope – in some cases, it might make sense to include an out-of-scope section. Especially, if you know the customer is asking for a minimal change and you know it probably should include more. For example, I recently had a customer request a change to the sales order invoice. After development and testing, they asked where the change is for the Free Text Invoice. The out-of-scope section could have called out the other areas where “Invoice” resides.

g) Descriptive Change – in order of the scope list, the details of the change or new windows and processes. This is the body of the FDD.

h) Security Concerns – description of any security concerns or restrictions that development might need to be aware of or need to build.

i) Test Scripts – List of test scripts, with details of actual tests and data to be used. A minimum of 3 and not just the happy or expected path.

j) Estimate – this should include, the development, testing, documentation, deployment, and training efforts associated with this FDD.

k) Approvals – I personally like physical approval; but I have seen SharePoint and other systems that allow for the client to accept the FDD via digital signature. In either way, the client needs to approve what they have asked for and what that will cost.

3.     Tips to make the FDD a solid FDD:

a) The FDD should tell a story of the new functionality.

b) Use the same data example throughout the document. For example, if one screen shot uses customer ABC, then use Customer ABC and the same transaction details throughout the FDD to show the progression of the data. If you change the data to another customer or a different transaction details, it makes it difficult to follow the story.

c) Use screen shots of changes and use some sort of image mock-up tool like SnagIt to highlight the change.  You can use numbers on the screen shot and reference the numbers in the descriptive section.

d) If the change is large, you may need to use a Process Flow Chart to explain the concept or decision points.

e) Use example data in a table if you are dealing with a variety of data options.

f) The FDD story should flow. If the parameter type window is going to have a new field that will be used in a process. Describe that change first, so when the developer gets to the process change, he/she understands where the new field came from.

g) Restrain from telling the developer how to code. Give them the room to be creative, its what they like to do.

h) Use the test scripts to explain additional scenarios. The more test scripts and scenarios that can be added to the FDD the better the developer will be able to handle the scenarios.

i) Make sure your test scripts deal with error handling. Create test scripts to force the errors to pop-up and explain what the error message should be. This is getting off the happy path for testing. It can be used to put rails up to keep the users on the happy path.

j) Have another consultant read your FDD before showing it to the customer or to the developer. Grammar and the story need to make sense.

k) Do not take an existing FDD of something that is in production and make additional changes. Write a new FDD referencing the older FDD as the base, but clearly stating all the new changes. 

The above lists may seem simple, but many of the FDDs I have seen are not fully vetted out and there could be an argument the consultant did not put a full effort into the work.  Spend time developing the test scripts and try to keep the flow clean. Certainly, try to keep the FDD simple and easy to understand. Your goal should be to be able to hand the FDD to the developer with minimal interaction and have the developer deliver a solid customization (can’t speak for a bad developer). The more you write and evaluate, the better you will get.

Hope you found a nugget or two in this article. If you have other tips, I would like to hear them. Send me a message or place comment below.