The software design documents have always been and remain one of the painful issues in software development. Have you ever come to a project that has been in progress for a couple of years, but, at the same time, you cannot figure it out in any way? The only technical task is written at the very beginning and does not reflect even half of the system’s functionality. This, frankly, is a very sad and byte-breaking sight.

Therefore, it is very important to initially build the process on all your projects so that there is no unidentified and undescribed functionality, all team members receive up-to-date information on time and everything is systematized. (Do you want to know, how to write technical documentation like a pro? Here is our previous post.)

What is all this for?

  1. Documentation provides a “common space” for the project. Any participant at any time can receive the necessary information both on a specific task and on the general direction of work.
  2. The team speaks “the same language”. After all, it is much easier to understand a person reporting “an error in a function described in Use Case No. 12” than “a dumb bug in the garbage that Matt did a month ago”.
  3. Documentation allows you to delineate responsibility between project participants.
  4. Only requirements that are carefully described can be checked for completeness and consistency. Otherwise, cluttered notes is a direct and very fast way to the fact that the boundaries of the project will creep as frisky cockroaches, and the functionality, conceived at the beginning, will not coincide with the customer’s wishes arising in the process.

So, when you take on a new project before you even open Xcode or Visual Studio, you need to have clear and consistent design goals. They should be written in the software design document. If this documentation is not prepared by the client in advance, then you should make a draft and send it for approval before starting work. If the client says: “Everything is on, we are short of time. We’ll deal with this later,” then keep in mind that this could mean big problems in the future. The software design document should not be voluminous, but the overall framework of the project should be indicated there.

Basic principles of software design documents

You can develop your own set of basic rules that allow you to effectively document, plan and control development in a comfortable environment for all participants.

  1. The documentation should not be redundant and voluminous. We do not write documents for the sake of pleasant tapping on the keys but to use them at work. An excessive amount of text is annoying and difficult to read.
  2. The whole project documentation should be interconnected and logical. If there is a document in the schema that is not linked to any other document, then it can be safely excluded from the schema.  
  3. All estimation of labor costs should be made only based on the described atomic tasks. It is difficult to evaluate the development of the “data entry subsystem functionality”. It is much easier to assess the tasks “development of a data entry form for Martians” and “development of a filter for the list of Martians”. The smaller the scored item is, the more accurate the aggregated score will be.
  4. It is always necessary to form stakeholder alert lists. A developer who learns about the need for revision three days before the release, an analyst who secretly changed the requirements and did not notify all interested participants about the need for revision and the PM who allowed such a situation happen will get the unpleasant reputation of a person, who does not cope with his duties.

Points to mention in the software design document

  • Brief project description
  • Requirements specification
  • Technical task
  • Estimating costs and justifying assignments
  • List of stages and work schedule
  • The current list of tasks performed by developers
  • Software design layouts
  • Software Testing Plan
  • Configuration management plan
  • Periodic progress reports
  • Report on test results and found defects
  • Source codes with a chronological list of changes
  • Stage presentations
  • Prototypes, models, experiments
  • Product

Let’s have a look at some of these points.

Functional Description: example

Description of custom application scripts:

  • First run
  • Creating a new scenario
  • Options
  • Background and foreground behavior

Bug Report

Bug Report appears in the process of system testing as a response to an error. Each document must be sure to refer to the corresponding Test Case. The document must contain:

  • screenshot of the error that occurred
  • description of previous actions. It is best to develop a template for such a description that is convenient for everyone – this greatly saves developers time when reproducing a bug.
  • textual error description

Hopefully, you find this article useful and interesting. Various issues are beyond the scope of this guide (for example, the use of standards, templates, process automation, etc.), but we will analyze them later. Stay tuned for our new posts!