Technical Documentation vs Software Design Documentation – Key Differences

designdocumentationlibrariessoftware

I am trying to start a documentation about a class library that is already finished/developed.

The purpose of the documentation is to be used by other developers in order to understand what kind of methods are included in this class library and how to use them. More specifically documentation like Javadoc tool that provides based on XML comments for each method and attribute of classes.

So far I have been reading about documentation type and it seems that Technical Specification and Software Design Documentation are those that provide such information.

But I am confused about them because I can not see a lot of differences based on some reading that I have already done.

For example here, it says that Software Design Documentation is used to give a software development team overall guidance to the architecture of the software project. And here it says that Technical Documentation is used for a new developer that join a software project. What kind of information would be useful to get introduced to the project?

From this point of view, it seems that those documentation tries to make a software developer familiar with what has been developed so far. But what is the difference and which one to use for my purpose?

Best Answer

What is a technical documentation ?

The real definition: Technical documentation means any document that common mortals do not understand because of some required specialized knowledge.

The bad news is that it won't help you to determine what to put in it. The good news is that you can from now on use the concept yourself to qualify anything that you do not understand: "Uh! These accounting guidelines seem to be a very technical document" (and all those except the accountants will nod, silently agreeing with you).

What is the objective of your documentation?

The real question: For technical writing, as for any writing, the first question is to know what is the target audience, and what the primary purpose of this documentation is:

  • Is it for new team members ? The most important thing is to give an overview (e.g. architecture and layers, main components), a high level domain model (i.e. context map), as well as some hands on information (e.g. directory structure, toolset used, naming convention, link to other important documents to read). The details will anyway be in the code be it in self-explanatory clean code or useful comments.
  • Is it for library users ? Your javadoc or doxygen will generate a suitable reference documentation based on comments that are embedded in your code (so hopefully easy to maintain). Unfortunately, this detailed information will not allow to understand easily the design of your library. Again, you need to provide some high level overview on the library's architecture, and how its different components interact and depend on each other. This kind of documentation is a MUST HAVE if your library is a commercial product sold on its own.

A fatal assumption would be to think that you could do a "technical documentation" that would cover any technical needs. The level of details to be understood by the team (that has to know the internals) and the users (who need to understand the use cases and the interface) is often very different.

Some advices

Grady Booch exposed in his book "Object Oriented Analysis and Design Technique", the content of a desired software documentation:

  • High-level system architecture
  • Key abstractions and mechanisms in the architecture
  • Scenarios that illustrate the as-built behavior of key aspects of the system

He further made a very specific point:

It is far better to document these higher-level structures, which can be expressed in diagrams of the notation but have no direct linguistic expression in the programming language, and then refer developers to the interfaces of certain important classes for tactical details.

Related Topic