1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Essays, opinions, and advice on the act of
computer programming from Stack
Overflow.
Find something
Latest
Newsletter
code-for-a-living
Podcast
Company
Developer Hiring
IT-Recruiting (German)
APRIL 6, 2020
A practical guide to writing technical specs
Writing a technical spec increases the chances of having a successful project, service, or feature that all
stakeholders involved are satisfied with. It decreases the chances of something going horribly wrong
during implementation and even a er you’ve launched your product.
Zara Cooper
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
1/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
As a so ware engineer, your primary role is to solve technical problems. Your first impulse may
be to immediately jump straight into writing code. But that can be a terrible idea if you haven’t
thought through your solution.
You can think through di icult technical problems by writing a technical spec. Writing one can be
frustrating if you feel like you’re not a good writer. You may even think that it’s an unnecessary
chore. But writing a technical spec increases the chances of having a successful project, service,
or feature that all stakeholders involved are satisfied with. It decreases the chances of something
going horribly wrong during implementation and even a er you’ve launched your product.
In this article, I’ll walk you through how to write a technical spec that ensures a strong product.
What is a technical speci cation document?
A technical specification document outlines how you’re going to address a technical problem by
designing and building a solution for it. It’s sometimes also referred to as a technical design
document, a so ware design document, or an engineering design document. It’s o en written by
the engineer who will build the solution or be the point person during implementation, but for
larger projects, it can be written by technical leads, project leads, or senior engineers. These
documents show the engineer’s team and other stakeholders what the design, work involved,
impact, and timeline of a feature, project, program, or service will be.
Why is writing a technical spec important?
Technical specs have immense benefits to everyone involved in a project: the engineers who
write them, the teams that use them, even the projects that are designed o of them. Here are
some reasons why you should write one.
Bene ts to engineers
By writing a technical spec, engineers are forced to examine a problem before going straight into
code, where they may overlook some aspect of the solution. When you break down, organize,
and time box all the work you’ll have to do during the implementation, you get a better view of
the scope of the solution. Technical specs, because they are a thorough view of the proposed
solution, they also serve as documentation for the project, both for the implementation phase
and a er, to communicate your accomplishments on the project.
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
2/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
With this well-thought out solution, your technical spec saves you from repeatedly explaining
your design to multiple teammates and stakeholders. But nobody’s perfect; your peers and more
seasoned engineers may show you new things from them about design, new technologies,
engineering practices, alternative solutions, etc. that you may not have come across or thought
of before. They may catch exceptional cases of the solution that you may have neglected,
reducing your liability. The more eyes you have on your spec, the better.
Bene ts to a team
A technical spec is a straightforward and e icient way to communicate project design ideas
between a team and other stakeholders. The whole team can collaboratively solve a problem
and create a solution. As more teammates and stakeholders contribute to a spec, it makes them
more invested in the project and encourages them to take ownership and responsibility for it.
With everyone on the same page, it limits complications that may arise from overlapping work.
Newer teammates unfamiliar with the project can onboard themselves and contribute to the
implementation earlier.
Bene ts to a project
Investing in a technical spec ultimately results in a superior product. Since the team is aligned
and in agreement on what needs to be done through the spec, big projects can progress faster. A
spec is essential in managing complexity and preventing scope and feature creep by setting
project limits. It sets priorities thereby making sure that only the most impactful and urgent parts
of a project go out first.
Post implementation, it helps resolve problems that cropped up within the project, as well as
provide insight in retrospectives and postmortems. The best planned specs serve as a great guide
for measuring success and return on investment of engineering time.
What to do before writing a technical spec
Gather the existing information in the problem domain before getting started. Read over any
product/feature requirements that the product team has produced, as well as technical
requirements/standards associated with the project. With this knowledge of the problem history,
try to state the problem in detail and brainstorm all kinds of solutions you may think might
resolve it. Pick the most reasonable solution out of all the options you have come up with.
Remember that you aren’t alone in this task. Ask an experienced engineer who’s knowledgeable
on the problem to be your sounding board. Invite them to a meeting and explain the problem
and the solution you picked. Lay out your ideas and thought process and try to persuade them
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
3/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
that your solution is the most appropriate. Gather their feedback and ask them to be a reviewer
for your technical spec.
Finally, it’s time to actually write the spec. Block o time in your calendar to write the first dra of
the technical spec. Usea collaborative document editor that your whole team has access to. Get a
technical spec template (see below) and write a rough dra .
Contents of a technical spec
There are a wide range of problems being solved by a vast number of companies today. Each
organization is distinct and creates its own unique engineering culture. As a result, technical
specs may not be standard even within companies, divisions, teams, and even among engineers
on the same team. Every solution has di erent needs and you should tailor your technical spec
based on the project. You do not need to include all the sections mentioned below. Select the
sections that work for your design and forego the rest.
From my experience, there are seven essential parts of a technical spec: front matter,
introduction, solutions, further considerations, success evaluation, work, deliberation, and end
matter.
1. Front matter
Title
Author(s)
Team
Reviewer(s)
Created on
Last updated
Epic, ticket, issue, or task tracker reference link
2. Introduction
a. Overview, Problem Description, Summary, or Abstract
Summary of the problem (from the perspective of the user), the context, suggested
solution, and the stakeholders.
b. Glossary or Terminology
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
4/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
New terms you come across as you research your design or terms you may suspect
your readers/stakeholders not to know.
c. Context or Background
Reasons why the problem is worth solving
Origin of the problem
How the problem a ects users and company goals
Past e orts made to solve the solution and why they were not e ective
How the product relates to team goals, OKRs
How the solution fits into the overall product roadmap and strategy
How the solution fits into the technical strategy
d. Goals or Product and Technical Requirements
Product requirements in the form of user stories
Technical requirements
e. Non-Goals or Out of Scope
Product and technical requirements that will be disregarded
f. Future Goals
Product and technical requirements slated for a future time
g. Assumptions
Conditions and resources that need to be present and accessible for the solution to
work as described.
3. Solutions
a. Current or Existing Solution / Design
Current solution description
Pros and cons of the current solution
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
5/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
b. Suggested or Proposed Solution / Design
External components that the solution will interact with and that it will alter
Dependencies of the current solution
Pros and cons of the proposed solution
Data Model / Schema Changes
Schema definitions
New data models
Modified data models
Data validation methods
Business Logic
API changes
Pseudocode
Flowcharts
Error states
Failure scenarios
Conditions that lead to errors and failures
Limitations
Presentation Layer
User requirements
UX changes
UI changes
Wireframes with descriptions
Links to UI/UX designer’s work
Mobile concerns
Web concerns
UI states
Error handling
Other questions to answer
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
6/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
How will the solution scale?
What are the limitations of the solution?
How will it recover in the event of a failure?
How will it cope with future requirements?
c. Test Plan
Explanations of how the tests will make sure user requirements are met
Unit tests
Integrations tests
QA
d. Monitoring and Alerting Plan
Logging plan and tools
Monitoring plan and tools
Metrics to be used to measure health
How to ensure observability
Alerting plan and tools
e. Release / Roll-out and Deployment Plan
Deployment architecture
Deployment environments
Phased roll-out plan e.g. using feature flags
Plan outlining how to communicate changes to the users, for example, with release
notes
f. Rollback Plan
Detailed and specific liabilities
Plan to reduce liabilities
Plan describing how to prevent other components, services, and systems from being
a ected
g. Alternate Solutions / Designs
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
7/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Short summary statement for each alternative solution
Pros and cons for each alternative
Reasons why each solution couldn’t work
Ways in which alternatives were inferior to the proposed solution
Migration plan to next best alternative in case the proposed solution falls through
4. Further Considerations
a. Impact on other teams
How will this increase the work of other people?
b. Third-party services and platforms considerations
Is it really worth it compared to building the service in-house?
What are some of the security and privacy concerns associated with the
services/platforms?
How much will it cost?
How will it scale?
What possible future issues are anticipated?
c. Cost analysis
What is the cost to run the solution per day?
What does it cost to roll it out?
d. Security considerations
What are the potential threats?
How will they be mitigated?
How will the solution a ect the security of other components, services, and systems?
e. Privacy considerations
Does the solution follow local laws and legal policies on data privacy?
How does the solution protect users’ data privacy?
What are some of the tradeo s between personalization and privacy in the solution?
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
8/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
f. Regional considerations
What is the impact of internationalization and localization on the solution?
What are the latency issues?
What are the legal concerns?
What is the state of service availability?
How will data transfer across regions be achieved and what are the concerns here?
g. Accessibility considerations
How accessible is the solution?
What tools will you use to evaluate its accessibility?
h. Operational considerations
Does this solution cause adverse a ere ects?
How will data be recovered in case of failure?
How will the solution recover in case of a failure?
How will operational costs be kept low while delivering increased value to the users?
i. Risks
What risks are being undertaken with this solution?
Are there risks that once taken can’t be walked back?
What is the cost-benefit analysis of taking these risks?
j. Support considerations
How will the support team get across information to users about common issues they
may face while interacting with the changes?
How will we ensure that the users are satisfied with the solution and can interact with
it with minimal support?
Who is responsible for the maintenance of the solution?
How will knowledge transfer be accomplished if the project owner is unavailable?
5. Success Evaluation
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
9/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
a. Impact
Security impact
Performance impact
Cost impact
Impact on other components and services
b. Metrics
List of metrics to capture
Tools to capture and measure metrics
6. Work
a. Work estimates and timelines
List of specific, measurable, and time-bound tasks
Resources needed to finish each task
Time estimates for how long each task needs to be completed
b. Prioritization
Categorization of tasks by urgency and impact
c. Milestones
Dated checkpoints when significant chunks of work will have been completed
Metrics to indicate the passing of the milestone
d. Future work
List of tasks that will be completed in the future
7. Deliberation
a. Discussion
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
10/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Elements of the solution that members of the team do not agree on and need to be
debated further to reach a consensus.
b. Open Questions
Questions about things you do not know the answers to or are unsure that you pose
to the team and stakeholders for their input. These may include aspects of the
problem you don’t know how to resolve yet.
8. End Matter
a. Related Work
Any work external to the proposed solution that is similar to it in some way and is
worked on by di erent teams. It’s important to know this to enable knowledge
sharing between such teams when faced with related problems.
b. References
Links to documents and resources that you used when coming up with your design
and wish to credit.
c. Acknowledgments
Credit people who have contributed to the design that you wish to recognize.
After you’ve written your technical spec
Now that you have a spec written, it’s time to refine it. Go through your dra as if you were an
independent reviewer. Ask yourself what parts of the design are unclear and you are uncertain
about. Modify your dra to include these issues. Review the dra a second time as if you were
tasked to implement the design just based on the technical spec alone. Make sure the spec is a
clear enough implementation guideline that the team can work on if you are unavailable. If you
have doubts about the solution and would like to test it out just to make sure it works, create a
simple prototype to prove your concept.
When you’ve thoroughly reviewed it, send the dra out to your team and the stakeholders.
Address all comments, questions, and suggestions as soon as possible. Set deadlines to do this
for every issue. Schedule meetings to talk through issues that the team is divided on or is having
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
11/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
unusually lengthy discussions about on the document. If the team fails to agree on an issue even
a er having in-person meetings to hash them out, make the final call on it as the buck stops with
you. Request engineers on di erent teams to review your spec so you can get an outsider’s
perspective which will enhance how it comes across to stakeholders not part of the team. Update
the document with any changes in the design, schedule, work estimates, scope, etc. even during
implementation.
Conclusion
Writing test specs can be an impactful way to guarantee that your project will be successful. A
little planning and a little forethought can make the actual implementation of a project a whole
lot easier.
Tags: bulletin, stackoverflow, technical specs
The Stack Overflow Podcast is a weekly conversation about working in so ware
development, learning to code, and the art and culture of computer programming.
The Stack Overflow Podc…
Programming in …
00:00
20:42
1X
SHARE
SUBSCRIBE
Related
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
12/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
code-for-a-living
JULY 13, 2020
Tales from documentation: Write for your clueless users
When you're documenting anything technical, it's easy to forget what it's like being ignorant of how the
so ware works, especially if you built the thing.
Ryan Donovan
60 Comments
Travis
6 Apr 20 at 1:29
Very nice writeup Zara
Reply
Zara Cooper
6 Apr 20 at 5:00
Thanks, Travis.
Reply
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
13/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Franco Brunetta Pan
6 Apr 20 at 3:05
Great article. It summarized all the reasearch I had to do months ago in a single page! It will
help a lot.
Reply
Zara Cooper
6 Apr 20 at 5:04
That’s great, Franco. I had the same exact frustrating problem earlier. Having a
template definitely helps out a bunch.
Reply
dipper
6 Apr 20 at 11:50
greate work, have any template more better
Reply
Fortunate Biira
11 Jul 20 at 3:02
I am a civil engineer and you just helped a great deal. Some people cannot
explain the thought process behind their good writing so it is di icult to learn
from them. Thank you. Thank you. Thank you.
Reply
Rama
16 Dec 20 at 1:23
Who would write a technical spec, a technical product owner or a coder
Reply
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
6A
20 t 10 30
14/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Zhiyong Liu
6 Apr 20 at 10:30
Ma’am, I did not find your Twitter account. Can I translate this article, please? I am the editor
of InfoQ China. I think your article, is really great and will help Chinese readers learn how to
write technical specifications. My Twitter account is @liu_zhiyong and I hope to follow each
other if that’s okay.
Reply
Zhiyong Liu
6 Apr 20 at 11:00
By the way, InfoQ China is a formal media organization, we strictly follow copyright
requirements, and all translations we publish will include the original information.
Reply
Ryan Donovan
7 Apr 20 at 8:57
Hi Zhiyong,
I’m afraid our legal department does not allow translations at this time because of
copyright issues. We appreciate your interest, but unfortunately, we can’t give you
permission.
Reply
Zhiyong Liu
8 Apr 20 at 3:09
Hi, Donovan,
Well, I’m very sorry to hear that. I respect your opinion and abandon the plan
to translate.
Reply
Matt
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
7 Apr 20 at 2:40
15/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
This is a great overview, gonna add it to my list of reference materials for new projects that I
check to see what I forgot to do!
Reply
Zara Cooper
9 Apr 20 at 6:00
Thanks, Matt. I’m happy it will help with your future projects.
Reply
Ibrahim
7 Apr 20 at 6:27
very usefull docuement
Reply
Zara Cooper
9 Apr 20 at 6:01
I’m glad it’s helpful, Ibrahim.
Reply
NUFOSMATIC
7 Apr 20 at 4:20
I would take the “so ware engineer” o of the first paragraph. You’ve written a guide that
could be applied to writing any engineering technical specification. Very nice, clear and
concise. A checklist every engineer should have in the back of his notebook.
If you’re a so ware engineer, I suspect that reading your code would be a very pleasant
experience.
Reply
Zara Cooper
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
9 Apr 20 at 6:02
16/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Makes sense NUFOSMATIC. A lot of what was in the template could be applied to a
wide range of specs. The clarity and conciseness of the article is mostly thanks to
Ryan Donovan’s thorough editing.
Reply
Joshua
8 Apr 20 at 12:34
Great article! Well written and laid out. I already write technical documentation for the
projects I work on and this will help me to have a more organized and template moving
forward.
Reply
Zara Cooper
9 Apr 20 at 6:03
Thanks, Joshua. I’m happy you’ll get some use out of it.
Reply
Star Ford
8 Apr 20 at 1:06
I write specs but I’ve been told the “new way” is just to dive in and be “agile” and that I
shouldn’t. But in my experience, planning in this way cuts down the cost of projects
compared to the “agile” way by half, or better, and improves clarity and bugginess in the
final UX. So I think that people are promoting specs-less development simply because they
don’t know how to write them. Hopefully this article will help the dying art come back to life.
Reply
Davis Peixoto
8 Apr 20 at 9:09
Anytime I hear someone saying we should “go agile and cut o the documentation” I
get a big red flag crossing my mind. Then I enforce that we should document what is
needed, whether it is a big amount of specs. Then I tell people about spec by example
way of doing things, so we can have the minimum. If I have room, I broke into BDD/
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
17/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
ATDD way. Finally, I usually present the articles related to the Joel Test, on Joel
Spolsky – co founder of Stack Overflow btw – which also says something about
having specs and how to write one, despite I think BDD can be used to promote a
having a spec to having a runnable spec.
Reply
Zara Cooper
9 Apr 20 at 6:28
I agree Star, first planning before implementing a design yields way more benefits
and saves you the agony of fixing something wrong in production or the final product,
especially when stakes are high.
Reply
Michael Gaylard
14 Apr 20 at 7:17
@Star Ford
I could not agree more!
30 years now in this business and it is only in the back half of this period that
specifications seem needless to some. So I have always written myself something to
follow even if no one else is going to read it. Agile seems to mean correcting mistakes.
I prefer not to make too many and have a clear idea of what I am doing and why I am
doing it.
My only criticism of this template is that it seems to roll a few documents into one – I
am more used (or used to be) to a hierarchy of documents than one colossal one.
Generally I have seen technical specs more at a Unit level whereas this seems to be
all-encompassing.
Reply
Meenish
2 Oct 20 at 5:10
Agreed somehow! Focusing upon specific module or/and writing technical
spec of module of the project would be enlarged. but having such content in
one place brought expert’s mind to further scrutinize and take in use as per
their consensus need.
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
18/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Reply
David
8 Apr 20 at 4:39
I recall developers and testers being confused when I spec’d errors for multiple rows
returned o a unique index key. I said today it is indexed unique and you cannot see this, but
this is not a database spec, it is a behavior spec., and it can still work if the index is dropped
and data is inserted twice.
Reply
Daniel Reeves
8 Apr 20 at 5:49
Nice write-up! I’m just a little scandalized that there’s no mention of Joel Spolsky’s classic
article on this: https://www.joelonso ware.com/2000/10/02/painless-functionalspecifications-part-1-why-bother/
Reply
Daniel Reeves
8 Apr 20 at 5:51
PS: And here are my thoughts on the di erence between a technical spec and a
functional spec: https://blog.beeminder.com/specs/
Reply
Zara
13 Apr 20 at 9:54
I don’t o en read Joel Spolsky’s blog but thanks for linking his post. I will
definitely check out both that and your post. Thanks for sharing.
Reply
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
19/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
John
8 Apr 20 at 9:12
Nice article. You’ve obviously put a lot of thought into the di erent aspects that should be
included in technical documentation. Unfortunately, it kinda reminds me of waterfall
development.
It seems like it’s trying to be the one mammoth document to describe an entire system.
Maybe this approach could work for a simple system.
A more complex system’s functionality would need to be broken down into small
manageable (easier to think about and to develop) chunks. I would have thought the more
practical approach would be to do write a series of user stories describing from the user’s
point of view what the system is expected to do and behave. From each of the user stories
develop a technical document to describe how from a developer’s point-of-view how the
user’s story could be technically achieved.
In a complex system, this one document would be HUGE. Not sure how easy it would be to
produce and maintain. Not sure how easy it would be to read. Kinda want to break the
document down so it is manageable and then it would be more likely to be used as a living,
breathing piece of documentation.
Anyway, those are my initial jumbled thoughts.
Reply
Zara
13 Apr 20 at 9:56
You’re right about not writing a single spec for one large system, John. I wrote this
from the perspective of a s/w engineer in a single team working on an already
established product in a larger engineering department (with other teams working on
other related products/system parts). From my experience, engineers who come on
to a team build on the existing product which is planned out in quarters, sprints, etc.
using task/story planning so ware. So in this case, engineers would be working on
features or smaller products and everything is already planned out in the product
requirements document and roadmap.
Reply
roll
9 Apr 20 at 12:38
Great article, So much detailed expain, and helps a lot.
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
20/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Reply
Zara
13 Apr 20 at 9:52
Thanks roll.
Reply
J Nagabhushanam
9 Apr 20 at 2:07
It is a well-written paper which helps a researcher and inventor to track his thoughts in a
way even a dumb promotor understands the significance, opportunities, technical
excellence, and usefulness of the proposed activity. Further, it helps one how to organize his
own thoughts and actions in realizing his dreams. Many thanks for your excellent
contribution.
Reply
Zara
13 Apr 20 at 9:49
Your completely right, J Nagabhushanam and thanks.
Reply
Nik Sumeiko
9 Apr 20 at 6:25
Zara, it would be helpful if guidelines in this article would be accompanied with links to spec
examples that are written according to these guidelines.
Reply
Zara
13 Apr 20 at 9:48
Apologies Nik. The initial article was pretty lengthy and required some trimming to
make it easier to review. So I cut out the example and some other parts to make it
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
21/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
easier to edit.
Reply
Denis ARGOUARCH
9 Apr 20 at 10:18
Thanks a lot for this guideline, it is a great help.
Reply
Zara
13 Apr 20 at 9:57
Thanks, Denis. Happy it was helpful to you.
Reply
Daniel Hernandez
9 Apr 20 at 2:24
Do you have any examples of tools that would be great for writing a tech spec?
Reply
Zara
13 Apr 20 at 9:47
Google Docs and Dropbox Paper a great because your team could leave comments
and collaborate on your spec.
Reply
Chamesou Toure
9 Apr 20 at 4:07
This is absolutely good stu !
Any comments as to have this ties to a User/Client side requirements…Any traceability
consideration
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
22/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Reply
Zara
13 Apr 20 at 9:45
Thanks, Chamesou. For user requirements, you’d translate them to user stories that
you would use as your goals. I guess you could include tracing and logging in the
monitoring and alerting section or just have a new section on its own. This is just a
guide. If parts of what you plan on building are not touched on here, add whatever
you need to it. Change this guide however you’d like to fit the needs of your product.
Reply
Nagesh
13 Apr 20 at 11:57
I le a comment on this one. Here is a way – https://medium.com/@nageshblore/theparl-approach-or-what-is-a-microservice-e48dd951ef3e
Reply
Jonathan Mchale
10 Apr 20 at 4:43
As a Product Owner (semi-technical) this is beyond useful! Thank you
Reply
Zara
13 Apr 20 at 9:42
Glad you found it to be helpful Jonathan.
Reply
Alfas
10 Apr 20 at 5:42
Very nice guide. Long time ago, I used to write specifications. I had nice templates then, but I
do not have them anymore. I need to write one more. It is so nice to see good template. I will
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
23/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
use it.
I hope this blog will be kept for long time. Still I am thinking to make copy of this template
just for safe keeping :).
Reply
Zara
13 Apr 20 at 9:41
Thanks Alfas. You could create a Google Doc template with just the contents part to
preserve it if you’d like and use it for your future specs.
Reply
Gustavo Di Salvo
10 Apr 20 at 1:41
Great guide. Just a nitpick: you mention there are 7 sections when in fact there are 8, and
you stopped numbering them a er 2 (“there are seven essential parts of a technical spec:
front matter, introduction, solutions, further considerations, success evaluation, work,
deliberation, and end matter”). Thanks.
Reply
Zara
13 Apr 20 at 9:52
Nice catch Gustavo, thanks.
Reply
Abdul Rauf
13 Apr 20 at 5:42
This is very informative. Good technical specs can save a lot of time of all stakeholders
Reply
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
13 Apr 20 at 11:56
24/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Nagesh
13 Apr 20 at 11:56
Excellent coverage!
I would like to add that, the stake from the ‘business’ organization needs to come out
strongly. See here – https://medium.com/@nageshblore/the-parl-approach-or-what-is-amicroservice-e48dd951ef3e – for a possible way to ‘bridge’ the business and technical
teams.
This blog post seems to be written from the point of view of a team that has assimilated the
requirements from the business organization and is then writing out a specification – for the
assimilated requirements – that will be turned into a code. That code will materialize,
eventually, into an artefact such as Docker image, binary, etc. The stake of the business
organization should flow throughout the spec and perhaps, into the artefact also.
Consider this.
1. Business organization presents a vision e.g. reduce IT spend by 50% over 3 years, etc.
2. Consultant turns the vision into 2 or 3 programs that need to be executed over 2 years and
support for 2 more years, etc.
3. Each program is broken down into projects e.g. db migration, refactor, sunset, cloud
native, new UI, etc.
4. Every project is translated into certain deliverables e.g. NodeJs projects, database DDL,
Dockerfiles, etc.
The business organization should be able to point to a project and drill down to a running
artefact in production. Similarly, the developer should be able to call out the purpose of
every artefact all the way upto the vision that triggered this project.
Reply
Hasan
22 Apr 20 at 10:38
Is there any good example that demonstrates this content?
Reply
Hayato
2 May 20 at 2:28
Great article! Thank you for sharing this.
I found that the heading “Further Considerations” is marked up with h2 while the other
headings are with h3. Also, only the first two, “1. Front matter” and “2. Introduction” have
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
25/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
the numbers.
Reply
Ryan Donovan
4 May 20 at 11:55
Thanks for the detail-oriented read — fixed!
Reply
Sarah
27 May 20 at 7:26
Wow, thank you for putting everything I was looking for in one place. I’ve spent a few hours
researching this, and I really wish I would have found your summary last week.
Reply
Nifemi Sola-Ojo
13 Sep 20 at 5:56
This is great
Reply
G V Sandeep
17 Sep 20 at 7:07
Very well put and a comprehensive list of items mentioned. Thanks!
Reply
Meenish
2 Oct 20 at 4:43
Thanks Zara for you wonderful input. It would great to share some sample Note.
Reply
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
26/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Jean Michel PetitBois
4 Oct 20 at 3:48
I have written both functional and technical specs for years (SAP, PeopleSo , Oracle, QAD)
and i agree with the author that they reduce significantly the margin of errors before Go-live
and specs can serve as a good way to further communicate the code story with new
developers…..
Now, I prefer the unit approach and not a single bloc document….
Jean-Michel
Reply
Milosz Galganek
12 Oct 20 at 8:36
Hey, thanks for the guide and for making it super specific like this! I think it’s important to
mention that how the specs will look should also depend on who they are written for (as in,
they should look di erent when they’re for your internal team vs. an external team.) My
colleague talked about that a bit in his article on project specifications. Check it out, I think
you may find it interesting: https://www.stxnext.com/blog/so ware-product-requirementshigh-level-project-specifications-guide
Reply
Leave a Reply
Your email address will not be published. Required fields are marked *
Comment
Name *
Email *
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
27/29
1/10/2021
A practical guide to writing technical specs - Stack Overflow Blog
Website
Save my name, email, and website in this browser for the next time I comment.
Post Comment
This site uses Akismet to reduce spam. Learn how your comment data is processed.
© 2021 All Rights Reserved.
Proudly powered by Wordpress
STACK OVERFLOW
Questions
Jobs
Developer Jobs Directory
Salary Calculator
PRODUCTS
Teams
Talent
Advertising
Enterprise
COMPANY
About
Press
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
28/29
1/10/2021
Press
A practical guide to writing technical specs - Stack Overflow Blog
Work Here
Legal
Privacy Policy
Contact Us
CHANNELS
Podcast
Newsletter
Facebook
Twitter
LinkedIn
Instagram
https://stackoverflow.blog/2020/04/06/a-practical-guide-to-writing-technical-specs/
29/29