Write amazing development specifications

Development Specifications are key to evaluate the effort needed to pull of a project and to have a written description of what has to be done for both parties to formally agree and be on the same page. It also aids in being able to go back to a reference document during testing and evaluation.

Though they should be written for projects of all sizes the project complexity and people involved determine the amount of detail needed in the actual document.

It is generally a good idea to have the specification be a little bit too detailed than to be to vague, but some teams may just be so magically connected that they beam detailled thoughts to each other communicating full features and designs in bullet points only.

Assume you are not one of these teams. - write a spec

The general practice of having UI be present as a rough wireframe (e.g. sketched on paper or via excalidraw) and if larger in scope as full design (e.g. Figma) and defining how each function, button and page should behave in clear language to someone that has no context of the system to be built at all is key.

If the specification can be read by a highschool student without any previous knowledge who may just need to lookup some industry standard terms (better if not), then any developer will be able to know what to do and you will be able to hold him to the document.

It goes both ways in that developers need to know what to build and tester neeed to know how to evaluate what has been built.

Looking at the reasons of project delays and budget explosions should also be reason alone to write specifications if the above mindset didn’t resonate cost and time will.

Source:

How to structure your development specification

Generally there is only two things each specification needs to accomplish:

1. Nail down what is to be built so anyone is on the same page
2. Provide a detailled construction plan so the house is built properly

therefore it is important to have an increcible sharp overview (summary) at the start and build into the details as one reads on.

A good outline we are following is

• 1. General Vision
• 2. Case Study
• 3. How to get there? (Milestones)
  • 3.1) M1: description of first milestone
  • 3.2) M2: description of another milestone
• 4. Estimate
  • 4.1) Timeline
  • 4.2) Cost

The process of writing a specification

Starting out by writing it from top to bottom and delivering different versions of the specification to clients as fast as possible to get feedback.

General vision

The general vision is very important to get right as it’s the direction you all go with. That needs to be perfect for all people. Generally you can get the vision through conversations (meetings). In these conversations don’t take everything said word for word, but think about the end user, the development journey and the customer.

The end user will likely appreciate something different then the customer is saying they want built so your job is to make sure that there is no big difference and the general vision is good of the end user. If the customer does not agree argue with them and learn their position. These conversations will improve the precision of the general vision, be open minded when writing and discussing with the client.

If you have the time and budget, doing user interviews or reading user reviews may be a good idea for the general vision and for larger milestones. Though usually applying common sense from the end user point of view works very well.

Never forget: Common sense makes sense. The user’s intuition when using the solution is always right.

Case Study

The case study is a simple review of how similar solutions already work, whether that is competitors or other applications in the space the end users may be familiar with. It could also include multiple samples and generally the feature working somewhere totally different and then transferring the learnings to the solution being specified for the customer.

The goal is to promote vision and dreaming by showing actual data and relevant examples.

After reading the vision and case study one should go “oh that’s what you want to build? yeah and that direction could work”.

The vision and relevant case study complementing each other to form that picture.

How to get there? (Milestones)

Each individual milestone is a step to take. Be precise in defining your steps. Many clear small steps are easier to take then one big step.

Define many clear, detailled small steps.

Within the definition of each step (milestone) include the vision of what to do, potential designs (user interface) needed and technical details.

Make sure that the description is written so the business person knows what will get done, the builder knows the direction of how to do it and the customer knows how to evaluate if it was successful or not based on users using it.

The more precise you can be the better, but be mindful that requirements may be changed and multiple options need to be considered.

If you need to consider multiple options define the testing of multiple options in the milestone so there is no dispute about changing and adapting requirements during the process which will shift budget and time expectations on all sides.

Describe the relevant documents and not only the clear outcome. If it is a software project relevant documents include code, and the end user documentation as well as developer documentation.

The end user documentation describes how a user is supposed to interact with the software (for small features that are simple enough this may be omitted), while the developer documentation should never be omitted and consists of the code being documented itself and a write up of the philosophy behind the code, data flow and any things to look out for as well as a getting started.

Estimate

Every single client will want to know how much it is going to cost before you solve the small little problems that are unpredictable.

Even if one says pay me per hour and I don’t know how long it is going to take, they will want to have a fixed number.

Why? because they need to know “if it’s worth it” and if they can afford it.

The second cost is time, if you are fast and the customer values it, it is worth more money.

Also time needs to be planned and scheduled as releases on customer side depend on it as does their business which also has other stakeholders.

That is why estimates are so important and why it is better to overestimate then to underestimate.

If there are big quesion marks note them down and define a potential solution in simple language that anyone understands.

• Example: If Milestone 3, which is scheduled for 1 day, takes more than 2 days the extra time will be charged at X rate.
• Example: If delivery material Y by the client is delayed by more than 3 days the extra time will be added to all following deadlines.

This doesn’t just apply to individual milestones but can be extended to the overall project if it makes sense. And they can also be used to provide guarantees to the client.

• Example: If Milestone 4 takes more than 8 hours, the milestone is dropped (or reduced to scope XYZ).

Talk about conditions and rather have something defined and not need it then to have arguments about something that could be clear beforehand.

Timeline

Geting the timing right is always hardest, but also most important. Why? Because how long something takes decides if it makes sense to do it and also due to human cost is a large factor in budget.

So how can we make sure we get the timing right? Luckily this is a development specification and not an investment thesis so you don’t lose money by overestimating the timing and always having enough time at the end.

If we overestimate the time needed we get two benefits:

• Customer is happy because we deliver (way) before the proclaimed delivery date
• If complications arise we have enough space to solve them without budget discussions and due date shenanigans

So how do you esimate a timeline?

Usually you have an idea on how fast you have done something in the past or how fast you can get something done based on experience and the milestone description at hand. That is why the milestone description and the vision need to be so clear, else your estimate here is worthless.

By the way dear customer this also includes you changing the requirements mid project, the previous estimates become worthless once we always change the spec.

Rule of thumb: take the first time that comes to mind and multiply times 3 or 4 to get a realistic estimate. -> think it takes a day -> say 4 days.

If it needs to get done faster, reduce the scope or state assumptions you are making to enable the faster delivery clearly in the estimate also mentioning the long estimate. That way both options are clearly communicated and there one can point to the specification in case of any discussions.

Cost

There are two parts of a cost estimate

• Human time (how many hours and how fast?)
• Third party cost (partners, infrastructure, assets)

How fast is important because that means you need to prioritize the proposal over other projects which needs to be paid for, otherwise it doesn’t make sense.

Then human cost usually is calculated by estimated time x cost per unit of time.

Third party cost are a list of all costs also associated with fullfilling the specification like freelancer estimates, infrastructure bills and other things you need to buy. Most development projects have API and server bills and some UI/UX designer cost to provide the high detail user interface to be implemented.

How detailed does the spec need to be?

The level of detail required depends on the size of the project.

Generally it makes sense to be as precise as possible, but sometimes that just means having a clear outline while other times the project is large (multi month +) which requires of course requires more detail as any change will propagate with more consequences in terms of time and cost.

For a simple 1 day to 1 week project there are likely 2-3 milestones where each one is clear and you just need to write it out while having some conversation to make sure what you wrote down fits and is understandable by all stakeholders.

For larger projects which have lots of functionality or more unkowns it gets trickier and you should go into more detail and split the milestones smaller, because that provides flexibility and detail in the estimate as well as in what you are actually going to want to have delivered.

And if you have to implement UI either state that you are the one providing a sample UI or have a full design delivered before you spend much time on the design as it is often chaning and will need small details like loading animations, position changes and the likes to be implemented after the fact. These changes all add up to in the end be the largest time sink of the whole project if not clearly defined before.

When the design is defined beforehand, the estimate can be accurate and the small changes are not many so one can just do them within the time and cost estimate.

Do I really need to have the UI defined?

When the UI is defined beforehand, the estimate can be accurate and the small changes are not many so one can just do them within the time and cost estimate.

Therefore if you can DO IT. If the UI will evolve later have the specification be a scratch design that illustrates where each button would be and how it would feel, but leave it out. Then once you get to touch something and have a feel design the user interface and add to the specification or make it a quick follow up job.

Most customers will not like that, but they will love it in the end because there is no discussions about UI going over budget, taking too long and the likes.

All parties will be happy.

Sample Specifications

• Coming Soon