All articles

6 Tips on How to Write a Good Project Specification (with Examples)

Looking for 6 Tips on how to write a good project specification?

If you are then you are already on your way to developing a great product.

Our data shows that 9 out of every 10 small businesses and startups don’t know how to write a project specification.

Get your project specification right and you will have made the first steps to creating a great product. Here’re a few amazing case studies of companies who hired DevTeam.Space to build their software products:

  1. Class Central – Search Engine
  2. DDKOIN – Cryptocurrency
  3. Mejorate – Healthcare Mobile App and Web Application

 

Contents

1. Specification document should be simple
2. Project description
3. List of all the pages/screens with all the features
4. User path
5. Design mockups or wireframes
6. Tech stack related information
Conclusion

What is a Project Specification?

In short, a project specification is a detailed description of objectives for any given development project. It lists goals, functionality, and any other information that is required for the developers to successfully complete the project.

Why a project specification matters

Why should you pay attention to the project specification document in your project? Let’s start with a hypothetical question, and let’s consider the example of the construction industry.

Can you imagine the short-term and long-term impacts of a construction project that was executed based on poor specifications? Depending on how sub-optimal the specifications were, the impacts could be serious! E.g., there could even be safety hazards resulting in loss of life.

Everything in the construction industry is tangible. You can see the plans, drawings, etc., and make sense of it. Construction engineers and workers have a clear view of what they need to do, thanks to the project specifications. Even then, poorly written specifications can result in big losses.

Now, consider the field of software development. It has a high degree of abstraction, and developers need great clarity about what they need to do. Such a high level of abstraction makes it even more important for you to get your project specifications right!

We have earlier cited the importance of software project requirements, specifications, architecture, etc. for the success of the project. Read our guide “10 biggest challenges when developing an app” for more insights.
</a

How to write specifications for a project: A few tips

How do you write great software project specifications though? You could certainly use some tips and best practices. Consider the following tips:

1. Specification document should be simple

Nobody needs to write a 20-page specification from scratch. You would spend days and weeks working on it. It’s not a philosophical document; it’s a very clear set of instructions about how your product will work. Use shorter steps and try to write your first version of project specification documentation in one, or max two hours. It should cover the following aspects:

  • Project description
  • List of all the pages/screens with all the features
  • User path
  • Design mockups or wireframes
  • Tech stack related info

The benefit of preparing the specification quickly is that you can share it with your colleagues and your dev team, get a lot of feedback and additional questions, so it will be much easier for you to write the next version, spending the same one to two hours. Usually, the second version of the specification is good enough to start the project, though you might want to go into more detail and iterate more.

Let’s go step by step and I’ll show you what should be in your project specification documentation.
</a

2. Project description

This should be a simple text, around half a page, describing your product. It could be a mobile app, a website, a chatbot, or a complex integrated solution – but you still want to put it all together in half a page. It should describe your project and explain your project objectives. In addition, you can include:

  • Success criteria – how to know if your website or app is doing its job
  • Website/app maintenance if needed and who should do that
  • Project timeline and a deadline
  • Desirable budget

Here is an example we used for the first version of the DevTeamSpace dashboard:

DevTeamSpace dashboard is an automated project reporting dashboard. It notifies dev team’s project manager and developers to post 2-4 lines of text updates on the project progress on daily basis. Once the updates are posted and approved, the dashboard sends automated notifications to the client.

Left side of the dashboard contains the project name, description, client’s name, email, and phone number. Underneath, it displays the dev team and a project manager. Below that, clients can link their project documentation, demos, etc.

On the right side of the screen, we display the overall project progress in percentages, estimated completion date, roadblocks, notes, and daily updates.

DevTeamSpace project reporting dashboard doesn’t have a chat window, so it looks clean and is easy to skim though the daily updates. If the client wants to reply to a daily report, he/she can click the “reply” button under the update and communicate directly with the developers via email, slack or skype.

The dashboard will be deemed successful if we see a significant decrease in questions about progress from the client, and a significant decline in delays due to efficient roadblocks tracking and daily written updates.

As you can see, it’s just half a page, yet it provides enough information and details about the project from a user perspective.
</a

3. List of all the pages/screens with all the features

This might sound complicated, but it’s really simple. You only need to create a tree list of all your pages/screens and features. Here is an example:

  1. Main page
    • Logo
    • Main menu
      1. About
      2. Services
      3. Clients
    • Sign in
    • Gest started
    • Main title of the page
    • Subtitle
    • Button “Get Started”
    • Logos of companies our dev teams have helped
  2. Sign Up Page
  3. Dashboard page

And so on, for every single page. It takes no time to write and creates a super clear structure for your product. If you struggle to create such a list, you probably don’t have a good understanding of your product. And there is no one better than you who should write it. So, if it’s hard for you to write, you should try to really focus on it and do your best. It will not only affect your project specifications, but also your overall business understanding and product user experience.
</a

4. User path

This is one of the most important parts of your specification. Here you explain how people use your product. You can make it in Word, PowerPoint, or even just draw it on paper and or flip board. Or you can use tools like iMindMap, Mindmaster, or DriChart. I have no affiliation with these products whatsoever, sharing only for your benefit. This is what the user path could look like:

Please don’t mix it with the user flow. User flow is a result. It shows you how your users go through your site, from page to page, and you can’t control it. It’s statistical information. You can find it in Google Analytics, for example.

 

The user path is something you design. You implement a certain structure, so people who use your product follow a certain path. It should also include:

  • User roles – what types of roles will your website/app users have (guest, editor, admin, etc.)
  • Feature requirements per user role.

Obviously, you can describe the user roles in a simple text format.
The cost of mistakes here is high. If you don’t plan this part of the specs well, you can end up with very disappointing results after the product is released.
</a

5. Design mockups or wireframes

This part of the specification is the place for creativity. It can be simply structured, or (if you have a designer) you can spend days on it. We are focused on simplicity today, so I would highly recommend you build wireframes. You can draw them on paper, or use simple graphic software, but I highly recommend going with one of the professional tools. Most of them are super affordable and even allow you to build one prototype free of charge. Here are some of the most popular ones:

InVision, Proto.io, Marvelapp, Pixate, Fluid UI

Keep in mind that if you want to build a custom design, completing this task is a must. On the other hand, if your project is small, you can use a template design. Here are some resources for that:
Design templates for mobile apps: AppDesignVault, CSSAuthor
Design templates for websites: TemplateMonster
</a

6. Tech stack related information

This part is not a requirement, because you can get an advice from your dev team on the best tech stack for your project. But if you have a specific request for a tech stack, make sure to describe it fully. For example:

  • Frontend
    AngularJS, CSS, HTML
  • Backend
    Ruby on Rails, MySQL, AWS
  • Other
    Stripe API for payments

The alignment of project specification with the IT architecture

Now that you know the best practices to write great project specifications, we recommend that you keep something else in mind. After you have baselined the business requirements for your project, you need to choose the right IT architectural pattern.

Your choice of architecture pattern matters! The architectural decisions are the first decisions you make during the project, and you need to get them right. You need to choose an architecture pattern that helps with the following:

  • Delivering your functional requirements;
  • Delivering the non-functional requirements like availability, reliability, etc.

You can choose from a range of IT architecture patterns, e.g., layered, event-driven, microservices, etc. Our guide “Large enterprise Java projects architecture” explains the popular patterns and you can read it for more insight.

You need to ensure that the project specifications you create align with your choice of architecture pattern. Developers will code according to the project specification. If the specifications don’t align with the architecture, then the code won’t align with it either. This can create long-term challenges for you.

 

The importance of reviewing a project specification document

You know the importance of reviews already, don’t you? “Verification” and “validation” are both important for the quality of a software product, and a review is part of verification.

 

While we often concentrate on code reviews, we need to remember that reviews should start earlier. Structured reviews of business requirements, IT architecture, and project specifications can help to find defects earlier in the life cycle.

Read “How to find the best software code reviewers”, where we have explained the importance of such reviews. Ensure that you conduct thorough reviews of the project specification document.

</a

Conclusion

Congratulations on making it this far! The above information could be overkill for a smaller project, or you may want to add extra details for a larger project. Logically, the larger the project, the more important a detailed spec becomes. Overall, when you are drafting your project spec, account for as much of the above list as possible.

DevTeam.Space is a vetted community of expert dev teams supported by an AI-powered agile process.

Companies like Samsung, Airbus, NEC, and startups rely on us to build great online products. We can help you too, by helping you to hire and effortlessly manage expert developers.

LinkedIn Facebook Twitter Facebook Messenger Whatsapp Skype Telegram