Onix stands with Ukraine. Please monitor current status here.

How to Write a Project Specification: Guide & Template

January 25, 2018

When starting a new project, have you ever felt as if you are setting sail for a distant treasure island? Ever felt lost at sea? Did you ever find yourself among mutineers who used to be your team, the ship of your project adrift, and the deadline looming ahead like rocks? 

How much does it cost to hire a dedicated team_-min (1).png

 

This article contains some project specification tips from Onix’s experience that will help you avoid such situations, sail faster and more safely, and eventually make it to the hidden chests of gold.

 

 

So what is a project specification?

A project specification in project management supports a successful, seamless development process since it defines a project's plan as a whole.

 

A treasure map is not a mere metaphor. A map is needed to locate a prize or for a trip. It can be represented as a plan for an activity or a specification for a project. Can you go after a prize without a plan? Well, yes - if it is hidden in your backyard, and you can dig it out on your own. 

 

However, this is seldom the case with startups and small businesses: the future product owner has either no means, skills, or resources but an idea or needs that must be met. Not much, but these two basic requirements, the ‘who’ and the ‘what’ of the product, are equal to the ‘X’ mark on a treasure map.

The ‘business requirements document’ is one of the most frequently used terms referring to a project’s ‘treasure map.’ Requirements specification, product requirement document, design specifications, functional specifications, functional spec, technical details of a project, tech spec, project spec, or simply specs - all used when speaking of the document, and the list is still not complete.

 

Some use the terms interchangeably when referring to the same document, while others identify different types of a specification by these words. Still, it would be fair to say that there are two primary types of specifications:

 

  • A functional specification describes what has to be implemented from a future user's point of view. For example, what the user needs or might ‘observe’ when interacting with the product. You can call it an ‘open specification’ because you only put the ‘X’ mark on the map and leave it to the pros to decide how to get there.

 

  • The other type specifies the inner workings of the proposed system and the measure by which success or failure will be assessed. This type is a ‘closed project spec’ because it describes the tools, technologies, or individual units that must be used to meet the need - like a definite route set on a map. This is a ‘technical project specification’ definition. A technical spec may incorporate or follow a functional spec for the same project.

Functional specifications tell what to do, and technically how to do it. But tell whom? The captain (a.k.a. the project manager) and the crew, i.e., the developers, designers, testers, or other professionals who will be charged with the task of turning your business idea into a prototype

 

When will you need the project specification?

If you were arranging a voyage, would you like to be able to calculate the time it takes you? To estimate the costs? To plan and know the options, risks, and ways around hazards? Would you like to sign up a competent captain and a diligent crew who perfectly understand the route and their tasks? Would you like to have a contract in place to ensure they bring you safely to the treasure island and back home safely after the treasure is found? 

 

You certainly would! 

 

The situation is very similar with software projects - you’d better have a project specification at hand as early as possible.

 

 

Generally, specifications are written at an early stage of the product development process because they determine product requirements such as:

 

  • what the developers will build
  • what tests will be run
  • what the stakeholders are receiving

project development process

Even some big corporations’ multi-year projects involved creating project specifications after migration to test and even to production, but let’s leave those scary tales to the mariners and look at the best practices instead.

 

How to write a specification for a project?

Professionals write the best specifications, but anyone can draw a fairly good ‘treasure map’ on their own. They just need to follow some important key points.

 

Find a template that suits your project needs

You can use a project specification template as a guide through a technical writing process. You can find a variety of these templates available online.

 

Gather requirements from all stakeholders

To make things easier, prepare a list of questions that would add more details about their expectations, the problems they expect the new software to solve, the type of data software should collect, and what processes it would automate.

 

Identify, list, and analyze your functional requirements

Start with general requirements for the product and then add more specific criteria. The requirements/criteria must be SMART, i.e., Specific, Measurable, Achievable, Relevant, and Testable. Read them critically, pretending you are not familiar with the idea yet, or as if you were seeking to minimize cost and effort. Show the draft to someone else. At the requirements analysis stage, it would be great to seek advice from other stakeholders, potential users, and software development professionals to evaluate all items and determine if they are essential to the product at the moment.

It is important to remember that many people with different backgrounds will be reading or even collaborating on the document, and all of them must understand the requirements. These tips should help:

 

  • Include a definition section at the beginning of the project spec to clearly define all terms and abbreviations you are using. One can make a product glossary for this purpose
  • Instead of using ‘it’ or ‘which’ in the text, always to try specify what is being referred to
  • Use the verb ‘shall’ to define specifically expressed requirements that must be fully and adequately met in the resulting product
  • Use short and direct sentences
  • Develop a table of contents
  • Assign to the document a title and control number with revision capability

 

 

Optional: draw wireframes or make accurate UI screenshots 

Some say that ‘a functional prototype is worth a 10,000-word specification’. However, this method instead belongs to the product design, and at the initial stage, without approved requirements and a team, you may need professional help to do this. So, before hiring a designer or business analyst, make sure your general requirements will be precise, at least to them.

 

 

Divide the work into specific tasks with deadlines

Project specification must describe the minute detail of either all or specific parts of a design, such as:

 

  • static structure (e.g., components, interfaces, dependencies);
  • dynamic behavior (how components interact);
  • the signature of an interface, including all data types/structures required (input and output data types in the information systems, exceptions);
  • deployment considerations (e.g., runtime requirements, third-party components);
  • detailed class models including all methods, attributes, dependencies, and associations;
  • the specific algorithms that a component employs and how they work;
  • physical data models, including attributes and types of each entity/data type, etc.

 

Seek a technical writer’s help

Technical writers would help translate a ‘user-friendly’ and functional spec into highly formalized technical language as the development phase requires. This will provide your project specification document consistency and clarity.

 

Sign It Off

When the team agrees that functional specification consensus is reached, it may be deemed ‘signed off.’ The developers and QA team can write source code and test cases using the functional spec as the reference. Suppose it is not a big project with complex functionalities to be implemented. In that case, you’ve been happily working with the team before, and there are no restrictions whatsoever - that’s it, happy sailing! 

 

Otherwise, you may need another iteration on the requirements specification to make it a full-fledged comprehensive technical specification.

specification development process

Whatever the format, a functional spec should enable both you (the customer) and the development team (contractor) to measure the degree of conformance. Both parties must achieve a consensus before writing source code or test cases, beginning debugging or making other time-consuming efforts.

 

Moreover, a good specification enables professionals to define the scope of work and provides a means for identifying options and risks early in a project - to decide whether it is worthwhile to set out with the map at all. Although a spec does not include cost information, it should help the development team estimate the job quickly and give you a more accurate quote. 

specification effectiveness

A tech spec document is essential when a contract is issued: acceptance criteria defined in a tech spec can be enforced under the business contract terms. (It’s worth mentioning that one of a project’s success measures is often called ‘quality/specification,’ i.e. ‘specification’ means ‘quality,’ and vice versa.) 

 

When experts write technical specifications, they list success criteria and add other essential factors, such as conditions under which the product must meet the specification, determine a life for the product, establish safety standards to be applied, etc.

 

Not surprisingly, the creation of project specification documentation has its own ‘specs,’ which professionals refer to as technical briefs.

 

What is a technical brief?

It is a project outline or a list of participants and roles in a project. It should help you save time writing and ensure that all involved can understand your plan for the project early on and be prepared for it. A technical brief usually implies the following steps:

 

  • Create a list of all persons who will to participate in the project, if known, from the principal stakeholder to the last cabin boy, including each person's contact information 
  • Outline each person's role in the creation of the technical spec (technical writing, review, decision-making, approval, etc.) 
  • List all the tasks and subtasks that must be completed, indicating the name of the person responsible for the task (in a dedicated team this task goes to the project manager) 
  • Indicate the due dates for each project part to be completed and the dates of all reviews 
  • If any decisions must be made, indicate when and how it should be done 
  • With some expert help, try to list all technology that will be used in the project, including software and/or hardware needed to complete the project 
  • Try to include any possible technical problems in the technical brief 

 

What information to include in your project specification

Every project specification is based on tech and engineering requirements and specific details of a particular project. Here is the list of what your project specification document should include:

 

Brief description of your company

Your development team should understand your customer’s identity. So you can include the following details about your company:

 

  • Sector of activity
  • Core services or products
  • Project stakeholders

 

However, there is no need to go into extra details. Just give enough information for the contractor to understand your company’s goals and your project idea.

 

Description of your project

Consider this your project presentation. Outline the project idea, briefly introduce the overall concept, and explain why you are creating the project. Subsequently, it should include:

 

  • Name of the project or descriptive title, so the team would understand what to expect right away
  • Identify the lay of the land of the project so that the team would understand the details and possible issues
  • Set SMART (Specific, Measurable, Attainable, Relevant and Time-bound) objectives for the project to move in the right direction

 

 

Description of your end-user persona

The more accurate the description of your end-user persona, the more chances you have to make the product your audience will love. The ‘end-user persona’ term refers to the fictitious profile of your end-user, with as much vital and relevant information about the product as possible, including age, gender, interests, income, etc.

 

Such information can be collected from various sources, such as:

 

  • Questionnaires for your customers
  • Marketing data analysis
  • Checking internet sources where users discuss issues your project can potentially fix
  • Use contact forms for more specific information, etc.

 

Depict your unique selling points 

You can identify your unique selling proposition through your primary and secondary competitors’ analysis and understanding of their strengths and weaknesses. Knowing your unique selling point will help you offer new value that might potentially beat your competition and help your product win the market.

 

Estimate your project budget

Describe the project cost structure and where the funds come from. The development company you’re partnering with can help you with estimations.

 

 

Define the deadline

Set a deadline by which the project must be completed, including the time required for each stage of the project, and set milestones to track the progress. You can request the help of your development team to set reasonable deadlines.

 

Translate project requirements into functionalities

Translate project requirements into functionalities to describe how the software should perform and what each functionality should achieve. Describe each as follows:

 

  • name
  • goal
  • description
  • subfunctions
  • level of priority

 

Describe how functionalities will be implemented

This part is about the tech requirements that would meet the needs of your end-users. Explain what types of features in the new product your users will benefit from, and the project engineer will describe how to implement them to the team.

 

Appendix

Here you can place details that the team will need to complete the project, e.g., wireframes, mock-ups, drafts, etc. It’s the reference point for them as they begin their work.

 

A Few Project Specification Examples 

Project specification examples, like this one ‘Requirements Specification document for a new web-based sales system,’ can be found all over the internet. This one is detailed, but not every project document will look like this. 

 

Here you can access a shorter example of a project specification document to develop that shows how to develop a forum for the library.

The following example contains a flow chart diagram outlining the product development process.

 

Conclusion 

 An adventure often starts with an idea, and a project specification document starts with core functional requirements, the ‘who’ and ‘what’ of a product - which means that virtually anyone can write them down. Or, you can skip the step, launch without a basic map, and hope for the best. However, in that case, beware

 

  • complex functionalities, e. g., web platforms/applications or mobile applications
  • big team projects
  • fixed-price projects
  • negotiating, signing, and fulfilling a formal contract
  • one-legged ship’s cooks with talking parrots on their shoulders

 

… Okay, the last is probably safe.

 

Do you need assistance with a specification? Are you confident about your ‘treasure map’? Are you looking for a reliable, seasoned crew? If you are contemplating a software project or would like an impartial review of your current product, drop us a line! The experts at Onix will be happy to offer professional advice.

 

FAQ

 

What are some essential issues a project specification should address?

A project specification is a complete description of a software’s functionality and purpose. It depicts how the software will be used and performance details, such as speed, availability, response time, etc. The critical issue it addresses is communicating to the developers what course of action they need to take.

 

How can I learn to write project specification documents?

While many organizations have moved to Agile and minimal requirements, knowing how to write a project specification document can be a benefit. The most common way to learn how to do it is by trial and error. Check examples listed in this article or search the web for more inspiration. There is no universal rule on how to do it, and every project specification document is pretty much unique.

 

What are the three main components of a project specification?

Generally, the components may vary from one project specification to another, but the following components are universal:

 

  • Scope of work
  • Description of the project, an implementation plan that includes drawings
  • Legal definitions and frames, including who is responsible for what parts of the project and roles distribution, e.g., tasks of a designer, product owner, developers, etc.

 

Why do I need a project specification for my project?

A thorough technical project specification ensures the overall progress of the project and its compliance with a project proposal:  

 

  • sets goals, expectations, and quality standards for a product;
  • motivates and gives job instructions to everyone on the team;
  • makes a great reference guide for the development team, leaving no room for confusion;
  • saves the time to collate accurate information and clarify instructions during the development;
  • provides a step-by-step plan for a project, outlining milestones to ensure the appropriate quality product delivery, on time and on budget;
  • as part of the contract documentation, prevents the team from changing the dev course;
  • remains a valuable asset even if you put off or cancel the project: you still can use the specs in the future or make it a sample when you undertake another project.

 

Written by:
Denis  Sheremetov

Denis Sheremetov

CTO at Onix-Systems

Development of custom solutions for all sizes of businesses. Ensuring efficient and secure technology use.

LinkedIn IconEmail Icon
Mila  Slesar

Mila Slesar

Writer