Can creating a Software Design Document after development be justified?

Question

I'm currently working on my graduation for my "Software Development" studies, in which I have to develop complex software individually in an external company. This all needs to be done in a structured manner, creating all corresponding documents.

For this project I have chosen to work with the IEEE standard documents: Software Requirements Document (SRS), Software Architecture Documents (SAD) and Software Design Document (SDD). Although taught otherwise in school, for this project I've chosen to create the SDD after development (instead of before). My reasoning is:

The company at which I do my internship has given me the instruction to create a complex piece of software, satisfying a certain set of requirements, in a experimental manner. Because of the amount of freedom which they have given me in the project definition, almost nothing is certain beforehand, and can best be encountered while experimenting in the development process. Additionally, I'm creating the software in an individual manner, it would have no benefit to anyone else in the company for me to make this Software Design beforehand. Doing it beforehand will just cost me a lot of time to change it later on, as I can be certain that with the uncertainties in the project, the design which I make beforehand will have to be changed a lot. This feels counterproductive to me.

Is this a good justification to create the SDD after development? If not, would there be any good justification for that?

Edit: The reason to create the SDD afterwards would be for future developers to continue on the project. I'm not going to be able to finish the whole project in my graduation period, so other developers will have to continue on the current codebase.

Answer 1

In IEEE Std 1016 Section 3.1 Software design in context, you can find this paragraph:

An SDD can be prepared and used in a variety of design situations. Typically, an SDD is prepared to support the development of a software item to solve a problem, where this problem has been expressed in terms of a set of requirements. The contents of the SDD can then be traced to these requirements. In other cases, an SDD is prepared to understand an existing system lacking design documentation. In such cases, an SDD is prepared such that information of interest is captured, organized, presented and disseminated to all interested parties. This information of interest can be used for planning, analysis, implementation and evolution of the software system, by identifying and addressing essential design concerns.

The authors of IEEE Std 1016 recognize that a SDD may not be created up-front. One may be created after the software system exists in order to capture information for interested parties.

Section 1.1 Scope also provides some interesting information:

This standard does not prescribe specific methodologies for design, configuration management, or quality assurance.

In the context of this questions, the key words are "configuration management". Configuration management not only applies to the software system being created, but any associated documentation.

In your personal situation, and in many situations, creating an SDD up front is a waste. David Arno's answer is close to being what I would consider the right answer. The true design of your software system is the code. However, you "create the SDD before" or "create the SDD after" are not your only options. You have a third option - evolve the SDD with the software system.

If you're following a standard such as IEEE Std 1016, you have requirements for an SDD. Specifically, Section 4 of this standard defines the content that you have. As you work through design decisions, begin to create the different viewpoints, views, and overlays. As you make decisions, capture the design rationale for them.

This will allow interested parties to follow the evolution of the software design without needing to dig into the code. Of course, people may have comments or suggestions. If you are updating the SDD, they can track your progress and give feedback on the approach early, which you can then incorporate into the product as well as the SDD. When you transition off the project, if the software code and the SDD are in sync, someone should be able to easily onboard and pick up the work.

Answer 2

If all you are looking for from the SDD is to communicate the design with others, then yes, you can create it after development. Only thing is, it is then called documentation.

However, I would like to point out that an SDD can serve another purpose as well. It can also help you to reason about design and make sure you "fail fast". This is a good thing, especially if a lot of things are uncertain beforehand because you can discard approaches that would not work throughout the entire implementation early on. It also can prevent you from focussing on technical details to soon, by not coding anything until you have figured out the design.

I'd advice you to at least make an attempt at the SDD beforehand. If you run into things where you are not sure how things would work, you can then make small prototypes of the problems you are trying to solve. This will give you experience in solving the specific problems for your project that will benefit the quality of the complete solution in the long run.

Answer 3

The one true detailed design document that you will create is the code. It precisely tells the compiler how to build your application. As such, your design cannot be complete until that one final build before shipping.

Any other design documents you create, such as an SDD, will need updating after you complete your design (code). Therefore, there is a compelling reason to write the SDD afterwards: you only have to do it once.

The obvious counter to this is, "how often do you really write an SDD after the event"? The app is shipped, so you aren't likely to want to spend time documenting at that stage. But this applies equally to updating an existing one. Which is worse, no SDD or an SDD that is wrong and can't be trusted?

There are two reasons for writing it in advance though. Firstly it may be a compulsory requirement on you to do so (not nice; but it happens). Secondly, creating such a document can help you formulate an overall strategy for the design. But that can done equally well by drawing pictures, scribbling notes etc in an informal way. And since it'll need rewriting later, there's lots of benefit to the "quick and dirty" approach to that up-front macro design process.

Answer 4

For me, it would not be a good argumentation.

If really needed, I would argue with a strong focus on prototype development for a better understanding of an unknown problem domain. However, even in those cases, some pieces of design would be useful before.

Answer 5

There is a case to be made for doing it up front anyway. Because you are doing this to learn about writing documents like this. Skipping this work because it may not be 100% needed here means you skip your learning.

A compromise could be to write it during implementation. Before each component / module / screen or other subdivision of your program, you need to think about it how you're going to make it. Then you add your decisions to your design document and then implement them.

If anything changes later, you update the document.

This has several advantages compared to writing after the fact:

• You'll learn to keep design documents updated when requirements change, a useful habit

• You'll learn to think about design before implementation

• It is not as mind-numbingly boring as writing design documents after the fact is

• If you run out of time, you'll have a design document describing what you have so far so others can continue your work

• It's not much extra work this way

• As your project goes on you may not be quite sure on why you yourself did something that way two months ago, and you'll have your notes to tell you.

Answer 6

System Design Document, a record of basic requirements plus (new features) updates as the project moves forward with new design and solution attributes. Maintained until project/solution has been delivered. Useful, it communicates to all concerned.