What should a good technical design document contain?

Question

When writing a technical design document of a yet non-existent application/system, what aspects would be most helpful for the developers - assuming that the person writing the document is not involved in the actual development? There are some obvious things, and standard structures, of course, like

• system architecture
• interfaces (external, internal)
• infrastructure
• component description
• use cases

I would be interested in a broader viewpoint, and also knowing what are the most often missing elements from a technical design document from a developer point of view?

Answer 1

For me, a design document answers the questions: How is the software built? and Why is it built that way? (I mean architecture, not Makefile), whereas a specification document answers the question: What shall the software do?

With this point of view, external interface should belong to specification document, not design document. This does not mean that there is no discussion about it during development phase, this means that developers of other modules want to get this information from general specification and not design of another component.

Answer 2

In terms of what someone not involved in development can contribute, I think a glossary is one of the most helpful. Ideally this section would be for definitions specific to the project, although it may help to have some more general definitions, depending on the document's audience (if this will be only read by the developers, or if you might have some others outside of the development team reading it).

The idea is to keep the team consistent with semantics so as to prevent confusion later on. For example, when developing a shopping cart process, the team should know exactly what constitutes an "order": if some members of the team think an order is created the moment a user confirms their purchase, while others think an order is begun the moment a user begins adding items to their cart, there will be issues. Getting everybody on the same page with these details can save them lot of headaches in communicating about the project's design.

Answer 3

In an event of more than one technology platform involved it would be an idea to insert TECHNOLOGY Break-down as well. Just a thought... Regards, Andy

Answer 4

You should be sure to include a section on assumptions and dependencies to detail what will be the limitations and boundaries of your system, and what must be true in order for it to function (eg, other systems must provide data, etc). This is important also for more business-oriented documents, as it can protect your team from failures of outside systems.

It is also helpful for the developers of the system, though, so they know exactly what their system must do, and where and how they will interact with other systems.

Answer 5

short, concise and useful.

Ivan

Answer 6

what Would i used to make a software... is any software to be install in my personal computer to make a software... designing software...