A while back, I had written why a functional spec is needed in addition to a PRD. So what does a good functional spec need to contain?
Here is what I consider elements of a good functional spec. I tend to use smaller paragraphs or bullets to make it readable. People tend not to read lengthy sentences or large paragraphs.
1. Problem statement: This section should clearly explain the problem you are trying to solve. This should not contain anything about the solution to the problem. You want readers to clearly understand the problem first.
2. Proposed solution: Now briefly explain the solution you are proposing to solve the problem.
3. Marketing Information/Justification: Things such as how big is the customer base that has this problem and why should we solve this problem (differentiation, tablestakes etc.)
4. Target Users: Who are the typical users who will use this? Internal to your company? External users? Experienced users? New users? All users?
5. Committed or Minimum Requirements: The requirements that have been reviewed and committed by Product Management and Engineering should be listed here. Unless all of these requirements have been implemented, the project will not solve the problem it is intended to solve to customer expectations. Or in other words, the new thing cannot be shipped in the product. Number the requirements instead of using bullets so that it is easier to refer to them during reviews, in emails, during discussions etc.
6. Requirements under Consideration: The requirements that needs to be considered by Engineering for implementation should be listed here. These are not committed to make this release. If time permits, Engineering will try to implement these in the current release (this never happens by the way). However, more importantly, Engineering has agreed to take them into account such that the current implementation will be able to support these requirements in the future. Again, number the requirements instead of using bullets so that it is easier to refer to them during reviews, in emails, during discussions etc.
7. Out of Scope Requirements: These would be requirements that have been agreed upon by Product Management and Engineering as out of scope for the current implementation. However, Engineering has agreed to take them into account such that the current implementation will be able to support these requirements in the future.
8. Proposed User Interface: This is where you would propose as to what the user interface needs to look like, what the interaction needs to be. This section will be written by an interaction designer or a graphics artist and if you don’t have such people, you should write them. I would not leave it to engineering to design the UI, you very well know what that will end up to be.
9. Typical Use Cases: Here you should list the most common use cases that should be supported by the current implementation. QA should be able to generate test plans based on these use cases. Flow charts are a very nice way to document use cases because it would mimic the workflow you expect the user to experience and are also very easy to understand. Doing flow charts also makes you realize the requirements you may not have accounted for.
I have used such a format for about 14 years now and engineering have always liked them because it tells them why to do something, how it needs to work etc.