For future reference

How to write a project specification

Alexey Semeney
Project Specification
© Shutterstock / SukanPhoto

Project specifications have something of a bad reputation, but they’re more useful than you’d think. In this article, Alexey Semeney explains why you should make a project specification and how they can save you time and money in the long run.

Project specifications have become misunderstood in the tech world. Big businesses tend to overestimate their importance, while many smaller companies think they don’t need them at all. I’m here to tell you that for most software projects, a project specification will be at least helpful, and probably essential. But, it also shouldn’t be the 20-page formal technical document you might be thinking of.

Let’s take a look at some tips to write great, useful project specifications for your projects.

First things first: What is a project specification?

A good project specification is a simple but complete description of a software’s functionality and purpose. It contains descriptions of how the software will be used from a user perspective and performance details such as speed, availability, and response time. Its primary purpose is to communicate to the developers what they need to do.

You can make a spec for websites, Android or iOS apps, or any tech project. It should be no more than a few pages and collaborated on by everyone involved in the project, from the project manager to the developers.

Do you need a project specification?

It’s fashionable these days to say that project specs aren’t ‘lean’ enough for startups. However, as Rian van der Merwe explains, not writing a project specification is an unnecessary risk. Thinking you’re a cool “gunslinger” that dives straight into the code for your MVP will cost you time and money later on.

The benefits of having a project specification are immediate. If you’re outsourcing your project to a development team, having an awesome spec can actually save you money right off the bat. When quoting a price for your project, development teams need to take into account all the possible risks. Anything slightly ambiguous will raise the price. A simple, concise spec will clear all of these up, and you’ll get the lowest possible price.

How to write a good project specification

1. Find a good template that works for your project

The best place to start is with a good project specification example, template, or outline. Here’s an example of a good outline to start with

  1. Description of the project and objectives
  2. List of all the pages/screens with all the features
  3. User path/stories
  4. Design mockups and wireframes
  5. Tech stack and other related info

The project description doesn’t need to be more than half a page. This part should describe the project and the objectives, and contain things like success criteria, budget, and timeframe.

The list of all the pages can be just a tree list describing the page structure, something like:

  • Homepage
    • Menu
      • About
      • Products
      • Testimonials
    • Login

The user path/stories section is where you really get stuck into things. This is where you can describe how different users will use your application. It will include all different possible roles (admin, guest etc…) and what features each will need to interact with your product effectively.

SEE MORE: Common sense software engineering: Estimates & project metrics

Mockups and wireframes are where you consolidate what you’ve got so far into something visual and concrete. You can use templating software such as Template Monster or even sketch them with pen and paper. It doesn’t really matter, the point is to have a visual representation that you and your design team can understand.

Finally, the tech stack information is what your developers need to decide on. They should have a great idea of what you need based on all of the above.

2. Collaborate on one online version

A project specification document should not be isolated or maintained by just one person. Ideally, you want a cloud document that everyone can view and collaborate on easily. Use Dropbox, Google Drive, or any collaboration tools you like. The important thing is that everyone is a part of building and maintaining it (more on this later).

3. Get the first version done fast

Create the document as soon as possible. Try to get your first version done in just a couple of hours. You can think of it kind of like your project spec MVP. Get something on paper, then send it to your developers for some feedback. You can all keep building and iterating until you have something useful.

Getting it done fast stops you from thinking about it too much, and becoming another project spec nightmare.

4. Write from a customer perspective

Apart from the budget, tech stack related stuff etc… most of your project spec should be written from a customer’s viewpoint. This is where user personas and storyboards really come in handy. That means writing things like “Users can login by clicking the “Login” button”.

A great trick for storyboards is to actually come up with characters with names that have uses for your product. This will help you visualize how they might use it in real life.

SEE MORE: Java 9: The draft Public Review Specification is out

5. Make things visual

A picture says 1000 words, and this is especially true when describing designs and layouts. Even a bad sketch can be great at clarifying potentially ambiguous things like positioning and sizes. You even add more visuals like custom graphs, charts, table, diagrams. Anything to help you and your developers understand things more clearly.

6. Keep working on it

Another classic mistake is ‘finishing’ a project specification before starting work on the project. A much better way is to have a living, evolving document that everyone collaborates on throughout the development of your project.

There will be things that change after you’ve started building your project, especially if you are using the MVP model of development (and you probably should be). Your document specifications need to be flexible enough to communicate these changes to everyone.


Bad project specifications are rarely fully understood by each team member and can be a drag. But, there are many benefits of having a great spec, and it’s definitely worth the effort.

Just follow these steps of using a template, starting early, using visuals, and continued collaboration, and you will have a project specification that is truly useful, saves you money, and doesn’t take too much time.



Alexey Semeney

Alexey Semeney is CEO at DevTeamSpace, AI-enhanced community of top dev teams.

Inline Feedbacks
View all comments