Programming/Design Docs/Requirements

What is a Requirement?

a thing that is compulsory; a necessary condition

Aside from the proposed solution, this is probably the most obvious section to include in a design document. This can also be one of the most difficult sections to fill out, especially if you aren't given user stories. If you've worked directly with customers and/or end users before, you know that what the user thinks they want is often different what what they actually want. Adding in additional layers of abstraction (communicating through representatives or project managers, for example) can increase the discrepancy. While there are no concrete steps to getting accurate requirements, here are some guidelines I've found useful:

• Ask if you can join the project manager when meeting with the client. It can be helpful to hear the client's words and emphasis directly.
• Make sure you understand the problem they are trying to solve. This way, you'll be able to make informed suggestions.
• Ask clarifying questions. There really isn't too dumb a question, I promise. Assumptions can cause unnecessary discrepancies so if you aren't sure, ask someone like the project manager or the client.
• Challenge assumptions. If someone uses "obviously" or "of course" in a statement, ask yourself (and maybe them) why. If there are restraints on technology choices or functionality, find out if they are realistic, due to budget or licensure, or artificial.

It is vital to realize that no matter how diligent you are, there will always be missed and/or changing requirements. It is less important to get all the requirements than it is to establish a feedback loop. Consider modeling your development cycle after a form of Agile development such as Scrum or Kanban instead of the traditional Waterfall in order to catch these discrepancies earlier in the development process.

Example

In the Problem Statement section, I outlined a list of user stories for a blog post exporting feature:

• As a blog owner, I can export a single blog post as a Word document.
• As a blog owner, I can export a single blog post as a PDF.
• As a blog owner, I can export a single blog post as a plain text document.
• As a blog owner, I can export all blog posts as Word documents.
• ...
• As a blog owner, I can export all blog posts in a tag as Word documents.
• ...
• As a blog owner, I can export a custom subset of blog posts as Word documents.
• ...

Instead of leaving the user stories as is, I would condense them into something more succinct and easier for me to understand:

• Blog posts can be exported by:
  • single post
  • all posts
  • tag
  • custom subset
• Blog posts can be exported to:
  • Word document
  • PDF
  • plain text

However, this is purely a personal preference. You can have them in any format as long as you (and the reader) understand what the requirements are.