Tutorial on Writing a
Design Document

chillibreeze writer — Aruna Wadhwa

Software development process or Software Development Life Cycle (SDLC) is the entire process of creating or modifying software products. All activities entailed in the development and modifications of a software product are addressed by an SDLC model. Broadly speaking, the following activities are involved in software development or modification: requirement gathering, risk analysis, designing, implementation, testing, operations, and maintenance. In an SDLC model, such activities are implemented in sequential phases.

Depending on the software product, professionals can choose an SDLC model to develop or modify their software. Types of SDLC models include:

Waterfall Model: This classic life cycle model divides software product development activities into phases. Each phase must be completed in its entirety before the next phase can begin.
V-Shaped Model: Uses the sequential path of execution of software product development activities, just like the waterfall model. However, in this model, testing activities are given more importance. Testing procedures are developed in early stages before any coding is done, using the SRS as the base document.
Incremental Model: This life cycle model makes use of multiple waterfall models. Here, software product development activities are divided into smaller, more easily managed iterations. Each iteration passes through requirement gathering, design, coding, and testing phases.
Spiral Model: This life cycle model is similar to incremental model, with more emphasis placed on risk analysis. This model has the following phases: planning, risk analysis, engineering, and evaluation. A software product passes through these phases in iterations (called spirals). The baseline spiral starts in the planning phase, where requirements are gathered and risks are analyzed. Each subsequent spiral is built on the baseline spiral.

Work products in SDLC

Various end products or work products are generated at each phase of SDLC. The work products of classic waterfall model are tabulated below.

Phase	Description	Phase product/activity
Initiation	Begins when a need for developing a software product arises.	Concept proposal
Concept development	Defines the scope of the proposed software product.	Scope document, Cost benefit analysis, Risk management plan, feasibility study
Planning	Involves estimating or planning for a software product to get the required resources.	Project plan
Requirement analysis	Involves ascertainment of user requirements.	Software Requirement Specification (SRS) Document
Design	This phase focuses on how to deliver the required functionality. Transforms the requirements into complete, detailed systems design.	Design document
Development	Converts design into complete software product.	Program codes, Databases, Test cases, reviews
Integration and testing	Confirms if the developed system corresponds to the requirements in the SRS.	Test case execution and test analysis report
Implementation	Involves implementation of the software product into a production environment and resolution of the problems identified in testing activities.	Test case execution and test analysis report, Implementation testing
Maintenance	Describes the tasks required to operate and maintain information systems in a production environment.	Post implementation reviews of the software product

As seen above, the design phase is a vital activity in the entire SDLC. In this phase, software requirements stated by the customer are modeled or transformed into design models that describe the details of data structures, system architecture, interface, and components. These design models are represented in the design document.

Components of design document

High Level Design
While designing a software product, the most important consideration is to ensure that each and every requirement specified by the customer is catered to. For this, a broader representation of the requirements in the form of design models is made. This process of modeling the requirements refers to High Level Design (HLD).

HLD essentially represents the software architecture ie various components and the overall look and feel or user interface of the software product. It is the first step to analyze and consider all requirements for a software product and attempt to establish a structure or design which is able to fulfill these requirements.

Preparation of HLD can be represented in the following steps.

The first step is to ascertain the components and then represent them. For this, the software requirements specification document (SRS) is used as the base document. The easiest method is to identify all the nouns in the SRS. Most often, each noun becomes the class.
Identify the constituents (attributes and methods) of each class.
Ascertain the overlaps, if any. For example, you may find that some classes you have identified are merely the attributes of another class. Also, identify the classes that are not important to the current design or structural representation. For example, user-interface components. These should be dealt with separately.
Write a description of each constituent of identified classes, no matter how trivial each constituent seems to be. This is called the data dictionary.
Establish the relationship between the classes. Say, for example, you are creating a database for tracking hospital records. A patient visits a doctor. Here, both doctor and patient are individual classes. The relationship between them is as follows: a patient visits a doctor. A doctor treats the patient. A doctor has many other patients. But a single patient usually visits one doctor in a particular department. Here, you are identifying the relationships between classes as well as identifying the numerical interactions or cardinality between the relationships. Cardinality can be one-to-one and many-to-many.

User interface design (UID):

The UID lays down the look and feel of the software product. For a GUI (graphic user interface) based software product, the UID includes:

all options on a menu bar
all the submenus and all options in these submenus
functionality of each of the mouse buttons, where appropriate
presentation of data, in form of graphics or text, or a combination of both
screen captures of prototype interfaces

For non-GUI applications, UID can be a Command Line Interface or Application Programmatic Interface (API). API is a collection of library routines that allow you to link or layer software components. For an API, the UID consists of identification of calling interfaces, names of object methods or routines, parameters and description of what they will perform.

It is important to consider that the software product and the user interface are independent of each-other. The user interface components should be as generic as possible.

Considerations for HLD
While documenting the HLD, the following considerations should be made:

How do you intend to organize the overall software product?
Have you clearly identified all the components and their interactions?
Have you converted all data definitions into data structures and types?
Are there any available re-usable components that can be used in your software product?
What will you build and what will you purchase? Cost analysis of building the components and procuring them commercially.
Have you identified the dependencies on external factors ie factors that are outside the control of your organization, which can impact future change management and software product updates?
Does the defined architecture adhere to organization standards and industry standards?
Have you ascertained the scalability of the system to handle the level of use and growth of components, such as data storage and new interfaces?

Low Level Design
Low level design (LLD), also called functional specification, provides the blueprint for coding. It details the HLD. For example, the classes you have identified during HLD are detailed in LLD. Here, you identify the objects (instances) that are required to implement the system. So, considering the example of an automated hospital system, the class doctor defines all attributes of doctors, such as name, age, qualification, charges, etc. The object ‘Dang’ refers to the specific attributes of a doctor Dang, whose other attributes are: 40, MD, Rs 700, etc.

The LLD:

defines algorithms and implementation details of class methods (functions).
establishes instantiation from class hierarchy and their relationships with one another, especially associations and cardinality.
provides algorithms for all class/object methods pseudo code. For a GUI (Graphic User Interface), the LLD describes how a particular selection by a user is represented. For example, in a text editor, a double click on the left mouse button will select a particular text, while right click will display a menu providing options such as cut, paste, font, etc.
uses state and event diagrams to define what happens when a user interacts with particular graphical components. It thus maps user interactions with graphical components to underlying application subsystems. For the text editor example, LLD maps a particular selection in the right click menu to the object that corresponds to cut, paste and font functions.
contains (for a non-GUI application) essentially the same contents as HLD, viz. details of all data types and functions. The LLD contains detailed algorithms that form a base for programming but not actual programming.

Thus, if you compare the process of writing a software design document to writing a book, the HLD will represent the chapters and sections. LLD will represent the bulleted items that you plan to cover in each section. You can elaborate these bulleted items once you start writing their contents.

Considerations for LLD
While documenting the LLD, following considerations need to be made:

Is the LLD a technical reference guide for the coding team to build code on?
Have you identified how issues such as hardware and software dependencies and limitations, performance requirements, security requirements, error handling and overall logging requirements will be addressed?

Template for writing a design document
Depending on your organizational requirements, you can select a template for your design document. For example, if your organization is following a particular quality model like CMM or ISO, you can use the templates specific to these models. Broadly speaking, a design document will contain the following sections:

Document information: provides information regarding the design document, viz. name of authors and document status (reviewed, draft).
Release information: name of the resources who have reviewed, approved and released the design document.
Document control information: specifies total number of pages, review period, information regarding the audience of the document.
Revision history: specifies version number, release date, description of individual changes made, resources who have approved the changes.
Purpose: lists the purpose of the design document and the intended audience.
Scope: relates the design of the document to the SRS.
Definitions, Acronyms, Abbreviations: provides definitions of all terms, acronyms and abbreviations used in the design document.
References: lists all documents referenced in the design document. It should also specify the sources from which these references are available.
Overall description: provides an overview of the software product for which the design document is being prepared.
High Level Design: details the high level design of the software product. This is represented by diagrams, such as system organization model (package diagram and deployment diagram) and High Level Application flow (represents flow of information in terms of processes).
Low Level Design: details the low level design of the software product. This is represented by diagrams, such as interaction diagrams, class diagrams, database design (entity-relationship) diagrams, state transition diagrams, and software interfaces of the system.

Chillibreeze's disclaimer: This is a contributed article and was published on Chillibreeze in March, 2010. The views and opinions expressed in this article are those of the author(s) and do not reflect the views of Chillibreeze as a company. Chillibreeze has a strict anti-plagiarism policy. Please contact us to report any copyright issues related to this article. The relevance of the facts and figures cited (if any) could change after a period of time.

More on Chillibreeze.com

Other popular articles on Chillibreeze

Agile Methodology of Software Development
E-learning: The Metamorphosis
Organizations and the Challenge of Innovation
Five Things Travel Readers Look For In a Travelogue
Two Epic Novels of Indian Literature

Out of 5 “chilies”, our editorial team gave this article...

—About our writer:

Aruna Wadhwa holds a professional diploma in International Business. She has worked in the capacity of an instructional designer and technical writer and has seven years of experience in the IT industry. She has also worked as a senior software quality assurance professional. Throughout her career, she has actively been involved in gathering the specifications, interacting with project managers, team members, and clients for producing technical documents and elearning courses. Her latest interest includes writing for acedemic research. She is based in New Delhi.

>> Read more articles written by Chillibreeze writers:

More resources for Writers on Chillibreeze.com

Chillibreeze offers Indian writers the opportunity to work on customer projects. We are also India’s biggest writer network and a one-stop shop for Indian writers and editors. The writers’ section on Chillibreeze offers freelance writers and editors a variety of tools to advance their careers. Resources for writers include:

Assessment of your writing, editing and proofreading skills

Writing courses

Expert Feedback on your article

An opportunity to promote yourself on our website

Top websites for Indian writers

Tips and resources for Indian freelancers

Book Publishing services

And more………………..

Explore our writers’ section using the links on our left-hand side menu. IMPORTANT! Don’t forget to

Tutorial on Writing a Design Document

More on Chillibreeze.com

>> Read more articles written by Chillibreeze writers:

Tutorial on Writing a
Design Document