How do you write a software design specification?

best-practices
resources

#1

I know it can be as little as a few paragraphs describing some functionality, but I’m really interested in how it is done properly.

Is there an outline of a technical design spec?
Are there any good books or online resources?


#2

For me, it has always depended on the needs of the team. What is right for one team will absolutely not work for another.

What is the situation you are particularly concerned about? I might be able to answer your question better if I know what your immediate needs are.


#3

@ClayDowling I’m thinking more in general terms, best practices or common styles.

  • to what level of detail should it be written?
  • what should be detailed?

I have read or seen people talk about how much better initial development can go when there is a well written design spec. For me let’s say for my next personal project, I would typically just start writing. Only knowing roughly what my program would do, not exactly how it would be accomplished or even everything that might be required.

So if I knew some ways design specifications were written, I could try writing them for my projects. To get experience in both directions; working from a design spec and writing one. I also feel like that might then give me a better idea of how long each task might take and so I could better estimate time to completion. Again for the experience.


#4

Here’s a link to an oldie-but-I-think-still-goodie first post in a series on this topic: https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/

One might also answer now (and by now I mean for the past several years, in the age of Agile), we do not write specifications; instead, we write user stories, manage backlogs, and create Kanban boards.


#5

Another approach that is definitely being used currently in software education, although I am not certain how often in the workplace, is UML: http://www.uml.org/


#6

I second UML. I would start with a UML describe and then describe it. It’s definitely very common in the workplace.


#7

Thank you all for the reading material. Looks like I have some homework ahead :blush:


#8

My personal preference is to go with the User Story route, which tends to be short, sweet, and just focus on the value I want to receive without paying attention to implementation. If this is accompanied with story mapping, where you figure out which stories together comprise something you can ship that will provide value, you get to a place where you can produce something useful quickly. For me, that’s important because early user feedback will inform what I prioritize next.

This is a bit of a larger topic. A colleague wrote a book on the topic, which will provide you with more depth: http://amzn.to/2u9CoBc


#9

I would actually distinguish between whether you are describing the problem to be solved or the reasons why you are proposing a particular solution to said problem. The former is what I typically call a Product Requirements Doc and the latter a Software Design Doc.


#10

I am most interested in a software design document. I think i understand the product side.


#11

Ok, great! The only think I have to add to the other answers is that an often overlooked but crucial aspect of a design doc is to list out the reasons for making decisions between various alternative solutions to the problem (and subproblems). Years later, it will help provide context for others who wonder why things were done a certain way.