Technical Specs: Practical Guide

How can one make sure that their project, a software project, for instance, is going to be a success? No one will give you a recipe that works 100% of the time, but there are ways to increase the chances. Before the actual development starts, technical specifications should be established. How will this help? Well, such specs will help draw up a detailed 3D model of your future project, and that will enable you to avoid a lot of mistakes and catch inconsistencies. Also, having specs mapped out allows the whole team and stakeholders to be on the same page – collaboration gets enhanced.

Technical specs really make development easier – with everything thought-out, the devs can rest assured their efforts won’t go to waste, they won’t need to worry about much at all except for the process itself. I know examples of developers writing the specs, too. However, this is clearly a task for a technical writer in my opinion. Without a doubt, technical writers will need to communicate with devs and SME’s a lot about this one – the whole idea behind technical specs is creating a trustworthy and viable document, and the needed depth can only be achieved through collaboration. It is important to prepare for such a task beforehand. Make sure to have a good read of the subject, go through available resources.

Now, to the specs structure. Here’s a technical specification skeleton you can use to develop your own tech spec:

First Page

It should contain introductory information like:

• Title
• Name of the author
• Date
• Team
• References (here you can add you Jira epic, any task links, etc.)

Project Overview

This is the section where you will give a brief overview of the project.

• Describe what this product you are creating the spec for is and what it is supposed to do. To be more clear, you can provide reference links to relevant documents (marketing or dev).
• Describe the context of the problem the product is supposed to be solving.
• A glossary can be added if it is necessary. It can include technical and project-specific terms for reference. This will help stakeholders and other teams involved understand the content better.
• Provide time estimates. It is understandable that you most likely won’t have any precise ETA at this point. It is normal.
• Describe the goals. This is the part where you enlist the goals of this project. Namely, what it is exactly that you would like to achieve after the product is ready. This is sometimes written as a separate section.

Product Requirements

As a rule, this section includes a list containing specific features of the future product. Describe how the final project should serve its purpose and solve the tasks it is set with.

Non-Goals

This is an important part of a technical spec that contains information about all the things the final product won’t do and the tasks it won’t be expected to solve. This sounds like a broad statement, but what you really need to do is narrow in on the areas where the product would be used and create a list of things you are not planning to work on, though they could be expected. For example, if you are developing a mobile app for photo editing and sharing photos, you can add the following non-goals:

• No chat functionality will be included
• Users comments can’t be upvoted or downvoted
• Animated gifs won’t be supported
• Etc.

This section helps you zoom in on only what’s crucial and leave out the rest.

Questions

Technical specs are a supplementary means for creating a quality product. At the moment when they are written, the idea of a product is not fully-formed yet. So, the section where you can add questions yet to be answered is often included into the structure. Put all open questions you and your team still have about the project, so you can return here any time to figure them out.

Plan

This section contains steps on how the project will help in completing the goals. What exactly it does and which technology is involved. Since nothing is finalized at this point, your plan of action can have alternative approaches. Make sure to dedicate a separate subsection for each approach. Make this section very detailed and specific.

Monitoring

Figure out the means to monitor success of the project. Usually, it is done by picking a number of metrics or criteria and evaluating the project against them. The main idea behind this monitoring process is ensuring the project is really accomplishing the goals set before it.

Deployment Plan

Describe the steps your team will take to deploy the finalized version of the project and make it available for the users. Explain in detail the sequence of action required on each step and what team is involved. An important part would be coming up with how you will let users know about this project. This can be done with release notes, email notifications, push messages, etc.

Further Considerations

This sections includes things not related directly to the development process itself, but important to consider:

• Cost of the project
• How the workload of teams will be affected
• How the project can be scaled in the future
• Are there any security concerns that arrive with the project implementation?
• Where does the project stand in terms of legal and privacy matters?
• Accessibility of the final solution

Timeline

Create a timeline with milestones. Specify which teams are involved and the scope of their work. Break down each task and describe it as thoroughly as the current state of planning allows.

Conclusion

This sample spec structure is a generalized one. In reality, specs differ from project to project. However, the backbone stays. Let’s imagine you created a draft of a technical spec. How can you make sure you are moving in the right direction with it? I suggest giving it to your colleague for a tech comm peer review. This way you’ll get great feedback to improve the document. Remember, technical specs are a big deal, and doing it right, you contribute to the success of the project.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices