Skip to content

How do I write the specifications?

Today I’m going to answer a question from Joel, the cofounder of a B2B marketplace. His question is:

How do I write the specifications for my startup project?

Before answering this question, let’s add a bit of context.

Joel and his cofounder have already developed the first version of their product. They are now tackling Version 2, and are considering outsourcing some of the development to a Web agency.

To help them answer this question, there are 3 things to consider:

What to consider

  • Specification level & details
  • Provider’s time
  • V-cycle vs Agile method

First, how deep and how technical we want these specifications to be. Then, the provider’s time required to establish the specifications. And finally, the management style we want to use: V-Cycle versus Agile method.

Specification level & technical details

So, how deep and how technical do we want these specifications to be?

3 levels of specifications

  • Business logic & customer journey map
  • Wireframe & design screen
  • IT architecture & code structure

1. Business logic & customer journey map

The basics of any specifications are to describe the business logic first. It’s impossible for any developer to develop an application if they do not understand how it’s supposed to work. It’s mandatory to define the final user steps by creating what is called the “user journey map.”

What is a feature?

Each step of the customer journey is called a “user story”, and we describe each user story like this:

As a {user}
I can {do something}
So that {I receive some benefit}

So each step of your customer journey map should contain this template.

2. Wireframe & design screen 

After creating the user story, we need to draw the wireframe and the design screens.

When creating the user story, remember to note the emotion you want people to feel in each step. Then draw each screen in a way that evokes these specific emotions and feelings, like excitement, curiosity, etc.

3. IT architecture & code structure

And last is the IT architecture and the code structure.

In this part, we share technical details like:

  • Languages/frameworks to use
  • Database services to use
  • Server architecture to handle a scalable amount of users, and
  • API services or Web services specifications (which is basically describing the information IN and OUT, travelling between the application and the server side)

These three levels: business logic, wireframe and design, and technical specifications are very important to understand the intended product, its requirements and the expectations of the founder.

As a non-technical founder, you can easily handle the 2 first steps.

And depending on how thorough you are in your specifications, the provider might need to dedicate some time on the third step to define the technical details and requirements, and how much time your development will take.

Provider's time

Keep in mind that, your provider is a company that is trading time, i.e. developers' time. But the salesperson and the project manager are also paid for their time spent with you even if you haven’t officially started to work with them.

So basically, if you want to save money and pay the best price for your development, do everything you can to save your provider time by giving as much details in your specifications as possible.

If you were to provide only the business logic specifications, your provider might have to work 3 full days just to draft your first development contract proposal.

Now if some providers accept investing that kind of time upfront, they will still find a way to make up for it and make you pay for that time, and that’s totally normal.

So if your goal is to pay the best price for the best result, consider this:

Quality in = Quality out

If you provide clear specifications, you will have a fair quotation as well as an application that really represents what you want.

Now you might wonder, “But how much time will it take to write the specifications?”

My reply is you should only create draft specifications. Do not spend time on creating beautiful and well-designed wireframes right from the bat.

You can either draw a simple version of your app screen with a pencil and take picture of it.

You can also take a screenshot of an existing app and add notes on what to change. You shouldn’t copy. I’m definitely not saying you should just copy. Just get inspired by apps that can afford millions in design budget. You know they’re not compromising design features for lack of money.

Wireframe tools

Now, if you want to make it more professional, you can use specific tools:

While using this type of tools, know that it’s not always a good thing to define every pixel of an app.

A decent provider should have enough experience and knowledge to put themselves in your shoes and suggest solutions that you might not have thought of before. This can elevate customer experience.

V-cycle vs Agile method

On that note, let’s discuss the V-cycle and Agile methodology.


With V-cycle, if you define every detail of you app, your provider will ask you to sign a contract and you will not be able to change anything in your app during development.

This is also called the waterfall model with the following steps:

  • Requirements
  • Design
  • Implementation
  • Verification
  • Maintenance

We can also represent it this way, as a V process.

It’s definitely the old way and is not tailored to build a startup.

Startups need to spend time with their customers to get constant inflow of new insights. If customers say that a specific feature is more important than another, you need to be able to change your development roadmap as soon as possible.

Agile method

That’s where we introduce the Agile process.

In a nutshell, the Agile process is like doing smaller projects with just one or 2 weeks of work, and repeat.

These short development periods are what we call sprints.

In order to pull this off, your specifications should show the 3 levels of specifications: 

  1. Business logic & user story
  2. Wireframe & design screen
  3. IT architecture & code structure

The business logic and user story, and you need to design the next wireframe to develop. What are the most important screens to develop first? In other words, do not specify in too much detail more than 2 to 4 weeks’ worth of work.

If you write the specifications for the whole project the upcoming year, for example, you will have wasted your time because you will have to change them over and over again.

The same goes for technical specifications.

Ask your developer to consider the project’s ambitions, but not to try to anticipate every intended functionality. Otherwise, it will take a year to create just the first version of your project.


So, to conclude and answer Joel’s question, when it comes to writing specifications,

  • Focus on the business logic description and the user story
  • Specify the most important screens that you need to develop, and
  • Never create detailed specifications for more than a month of work because you might want to change it during development

Now if like Joel, you have a specific question for your project, just go ahead and ask on

I will do my best to answer your question by video or redirect you to an existing content that will answer it.

I publish a new video every week, so subscribe now and learn how to be better at tech management and build a successful startup.

Also be sure to go through our other content here at to learn more from real startup growth experiences.

I’ll be waiting for your questions, and I look forward to seeing you in other videos. Cheers.