Your Treasure Map: Key Benefits of Having a Project Specification

Starting a new project, have you ever felt as if 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? This article contains some tips 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 treasure map is not a mere metaphor. You need a map to locate a treasure on it. You need a roadmap for a trip. A plan for an activity. A specification for a project. Is it possible to go after a treasure without a map? Well, yes – if the treasure cache is hidden in your backyard and you can dig it out on your own. However, this is seldom a case with startups and small businesses: the future product owner has either no means, nor skills, nor resources, but has an idea or a need that must be met. Not much, but these two basic requirements, the ‘who’ and the ‘what’ of the product, are actually equal to the ‘X’ mark on a treasure map.

The ‘requirements’ is not just a random word either. ‘Business requirements document’ is one of the most frequently used terms when referring to a project’s ‘treasure map’. Requirements specification, product requirement document, design specifications, functional requirements specification, functional spec, technical brief, tech spec, project spec, or simply specs – are all used when speaking of the document, and the list is 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 what they 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. Let it be a ‘technical specification’ definition. A technical spec may incorporate or follow a functional spec for the same project.

Basically, functional specifications tell what to do, and technical – how to do it. Tell whom? The captain (aka 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 reality.

When will you need it?

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 ahead and know the options, risks and way rounds? Would you like to sign on a competent captain and a diligent crew who perfectly understand the route and their task? Would you like to have a contract in place to ensure they bring you safely to the treasure island and back home 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

• what the developers will build
• what tests the testers will run
• what the stakeholders are getting

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

How to write a technical specification?

The best specifications are written by professionals, but anyone can draw a fairly good ‘treasure map’ on their own – just need to follow some key points.

First of all, 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, from potential users, and from software development professionals to evaluate all items and determine if they are really 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
• Instead of using ‘it’ or ‘which’ in the text, always specify what is being referred to
• Use the verb ‘shall’ to define specifically expressed requirements that must be fully and properly 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

Another popular method of writing a functional specification involves drawing wireframes or even accurate UI screenshots. They even say that ‘a functional prototype is worth a 10,000-word specification’. However, this method rather belongs to the product design, and at the initial stage, without approved requirements and without 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 clear at least to them.

Whatever the format, a functional spec should enable both you (the customer) and the development team (contractor) to measure the degree of conformance. It is crucial that both parties should achieve the consensus before writing any 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 itself does not include cost information, it should really help the development team to estimate the job quickly and give you a more accurate quote.

When the team agrees that functional specification consensus is reached, it may be deemed ‘signed off’. Using such functional spec as the reference, the developers and QA team are able to write source code and test cases. If it is not a big project with complex functionalities to be implemented, 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.

A  tech spec document is especially important when a contract is issued: acceptance criteria defined in a tech spec can be enforced under the terms of a business contract. (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 technical specifications are written by experts, they not only list success criteria, but also add other essential factors, such as conditions under which the product must meet the specification, determine a life for the product, establish safety standards that are to be applied to the product, etc.

A technical specification should divide the work to be performed under a contract in the completion of a project, typically into specific tasks with deadlines, and 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.

Technical writers may also need to translate the ‘user-friendly’ prose of a functional spec into highly formalized or abbreviated technical language as required for the development phase.

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

What is a technical brief?

Basically, it is a project outline or a list of participants and roles in a project. It should help you save time writing, as well as 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:

1. Create a list of all persons who are going to participate in the project, if known, from the principal stakeholder to the last cabin boy, including each person’s contact information;
2. Outline each person’s role in the creation of the technical spec (technical writing, review, decision-making, approval, etc.);
3. List all the tasks and subtasks that must be completed, indicating the name of the person responsible for the task;
4. Indicate the due dates for each project part to be completed and the dates of all reviews;
5. If any decisions must be made, indicate when and how it should be done;
6. 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;
7. Try to include any possible technical problems into the technical brief.

So, why a project spec?

The document alone sounds like a lot of work, doesn’t it? However, a detailed and through project technical specification is certainly worthwhile because it

• clearly sets goals, expectations and quality standards for a product;
• motivates and gives job instructions to everyone on the voyage;
• makes a great reference guide for the development team, leaving less room for confusion;
• saves the time that would be required to collate accurate information and clarify instructions during the development;
• provides a step-by-step plan for a project, outlining milestones, to help ensure the appropriate quality product is created on time and on budget;
• as part of the contract documentation, precludes the crew from changing course or giving you ‘the black spot’;
• after the project, provides a basis for technical documentation for the product, design documents of a later version of the product, etc.;
• 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 voyage.

An adventure 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 are 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, why not drop us a line? The experts at Alternative Spaces will be happy to offer professional advice.

Content created by our partner, Onix-systems.