For the past three months, I’ve been a Software Engineering Intern in the Connections & Add-ons team here at FreeAgent. We look after a number of features that allow FreeAgent to work with third-party services: if a business owner wants to get paid faster, they can add a PayPal, Stripe, GoCardless or Tyl payment link to their invoices; if they need to get their business insured, they can sign up for a Hiscox insurance policy directly through FreeAgent; and if they’re looking for an accountant to work with, they can sign up with one of our CoPilot practices.
Recently, I’ve been working on writing a tech spec for the work that we’re planning to do in the next few weeks. We want to give the Connections & Add-ons page a rejig, a lick of paint, and then introduce PayPal as an option to sit alongside the other payment providers. Currently, the page looks like this…
…but the new update is coming soon.
As mentioned, I’ve been working on a tech spec for some of this work related to moving PayPal from one area of the app to our newly designed Connections & Add-ons page. I thought I’d give you an insight into what I’ve learned whilst writing my first tech spec as a FreeAgent intern. So, talking of tech specs…
What is a tech spec?
A tech spec – short for ‘technical specification’ – is a document that outlines a problem to be solved, why it needs to be solved, the requirements of the solution, and the proposed solution to the problem – essentially it’s the What, Why and How of any software engineering related problem.
As the name suggests, a tech spec can be quite technical and it’s usually written by an engineer. Once written, it can then be shared with the wider team (fellow engineers, product managers and designers), who will discuss solutions to specific issues, answer any open questions and offer suggestions around the proposed implementation.
Another important aspect of a tech spec is that it outlines any other stakeholders involved in the project. For example, a stakeholder could be another team within FreeAgent or it could be an external third party.
Why do I need a tech spec?
When starting a new project or piece of work, it is very tempting to jump straight in and start writing code (I’m definitely guilty of this!). However, the planning stage of any software development project is just as important as the actual coding stage.
Most software projects follow a similar pattern:
💡 Discovery – what is the problem that we are trying to solve?
✏️ Design – how might a solution to this problem look?
📄 Technical specification – what do we need to consider and how are we actually going to solve it? How are we going to break this work into manageable chunks?
🔎 Refine – have we covered everything? Are there still any open questions?
🏗️ Build – time to write some code…
✅ Deploy – time to share your new features or changes with users.
Notice that the tech spec stage is after Design but before Build. If we were using a very linear software development process (for example, the Waterfall model) and we got our design and planning stage wrong, it could be time-consuming and expensive to make changes during the Build stage. If you instead use the Agile methodologies, it can be a lot easier to make last minute changes, however, it’s always best to have a solid plan of action and anticipate any blockers from the start – this is exactly what a tech spec is for.
Another benefit of a well written tech spec is that it keeps everyone in the team on the same page. My team, like most teams at FreeAgent, isn’t solely made up of engineers – we have a product manager and a designer too. When embarking on a new piece of work, there are a lot of engineering, product and design considerations that need to be taken into account and it can be useful to summarise these in one document whilst thinking about the implementation.
How do I write a tech spec?
You can choose to write your tech spec in a few different ways but most tech specs follow a similar format. In the Connections & Add-ons team, we have a good template so I decided to closely follow that, therefore, my tech spec was made up of the following sections:
Summary and motivation
What are you doing and why are you doing it?
Even if the reader isn’t familiar with the project, they should be able to read this section and be left with a good understanding of what you are attempting to achieve. If possible, try to make this section readable to a wide range of audiences (i.e. not just fellow engineers).
In my case, this started with something like: “We want to introduce a PayPal card on the Connections & Add-ons page so that users are able to see and compare each payment provider side by side.”
Considerations
Is there anything that you need to think about before making any changes? Does the project impact other areas of the codebase?
If you’re working on a fairly large codebase, like FreeAgent’s, it’s likely that your work will touch a number of other areas within the codebase. If this is the case, you should outline what impacts your work will have on those other areas and what you plan to change. Also, if there is some technical debt that needs to be cleaned up before you begin your work, this is a good place to talk about that.
As I mentioned before, your tech spec will likely have a list of stakeholders. If your work affects another area of the codebase, then the team that usually looks after that area should become a stakeholder in your project.
For my tech spec, this went something like: “As PayPal currently exists within the ‘Banking’ area of FreeAgent, we will have to ensure that users are redirected back to the correct section on the Connections & Add-ons page once PayPal has been successfully set up.”
Scope
What will and what won’t you be changing?
When you begin coding, it’s easy to get carried away and build or change more features that you were initially planning to do – this is known as scope creep. In this section of your tech spec, you should set some boundaries so you don’t end up with scope creep and you manage to finish the piece of work on time.
In my tech spec, this went something like: “We will be keeping the current code that handles the connection to the PayPal API; however, we will be moving the PayPal payment provider option from the Banking area to the Connections & Add-ons page.”
Related work
Is this piece of work related to something else? Is it a small part of a bigger project? Is there some future work planned that is based on this work?
If you’re working on a standalone piece of work, then you could probably skip this section. However, if your work is part of, or closely related to, another piece of work or project, then you should give a brief summary of that and how this piece of work fits into the overall goal of the wider project.
In my case, this went something like: “We want to bring PayPal to the Connections & Add-ons page so that users can easily compare between all of our available payment methods. This piece of work is part of a wider refactor and redesign of the Connections & Add-ons page to ensure that it is easy to navigate the page and users can compare all of FreeAgent’s available integrations.”
Implementation
How exactly do you plan to build this feature?
If you love to talk about code, then this is your time to shine – the more detail the better. In this section you should go into great detail about what changes you’re going to make to the codebase and how these will help solve the problem.
For my tech spec, this section was quite large. It covered some topics including:
- Creating a new controller (as we use Ruby on Rails/MVC at FreeAgent) and the list of methods that the controller will have and what each method will do
- Making changes to the app’s routing so that requests are sent to the newly created controller
- Creating the new HTML views and making changes to the existing view on the Connections & Add-ons page
- Writing new RSpec tests
- Creating a new Knowledge Base article with screenshots and updating any existing ones
What’s next?
Now that you’ve got a solid plan of action, you’re ready to start building! During the build stage you can regularly refer back to your tech spec to check that you are on track to implementing everything that you initially set out to do.
Whilst the PayPal work is still in progress, the team and I have regularly checked our progress against the tech spec to keep us all on track. The newly designed Connections & Add-ons page and PayPal integration will soon be live on FreeAgent!