A system design document is a detailed description of the system requirements, operating environment, architecture, files and database design. It also describes the input format, different interfaces, output layouts, processing logic and detailed design.
Writing a system design document can be quite technical. However, it does not have to be as hard if you know exactly what to include and how to frame it. In this article, we take a look at how you can write a good system design document.
We will walk you through all the necessary steps in coming up with this ‘elusive’ document to ensure that you have a gist of what is expected.
1. Have an Introduction
Every document on the face of the earth begins with an introduction. Here, you should offer an overview of the system and any other information to place the system in context. It would be best to break down the introduction into four parts for organization and detail.
The first section under the introduction should be the purpose of the document. Even though we all know that this is a system design document, its purpose still has to be clearly spelled. This should follow an overall description of the SDD.
The second section under the introduction is the scope. Here, you should discuss the range of information that the document covers regarding the system design and how it accomplishes its purpose. Also, be sure to break down and discuss this further into two parts, the in scope and the outs-scope.
While still in the second part under the introduction, you should discuss the assumptions that the system should be based on. These are the key conditions that must be met for the successful execution of a project.
Like in key documents such as the root cause analysis report, you need to include the methodology, tools, and technique used in the system and come up with the system design document. Ensure that this is as detailed as possible. This will take up the third section of the introduction.
The reader or intended audience needs to have an easy time going through your document. Therefore, make sure that you note all the acronyms and abbreviations used in the document in the fourth section under this part. Some of the common ones will be SDD, which refers to the system design document and the GUI, or Graphical User Interface in full.
Also, while still on the introduction, remember to include the references, which is basically a bibliography of the key project references and deliverables that have formerly been produced or used.
2. Provide a Design Overview
The second part of the system design document is the design overview. Just like the introduction, you should also break this down into four parts. If you are wondering what is expected of you while writing the system overview, it is a narrative form of the system without any technical terms. You can provide a high-level system architecture diagram that shows a subsystem diagram where necessary. This can show the interface or external systems. You can also include a high-level context diagram for the systems and subsystems where applicable.
Remember, the essence of the system overview is to explain the system in non-technical terms. It would help if you also referred to the RTM or the Requirement Trace Ability Matrix in the Functional Requirement Document, which should help you identify the functional requirement allocations into the system design document.
The first section under this part is background information, where you are expected to give background information on the system. The second part is the system evolution description, which provides concise information on the system’s modifications.
The third part under this is the required environment, where you are supposed to list the proposed or required managed environment. A managed environment is one coordinated by humans and can take several forms.
The fourth and last part under the design overview is the list of constraints. Here, you should describe any global limitations or constraints that significantly impact your system’s software design. You should also discuss the associated software.
This section will also include any assumptions that the project team made in developing the system design. You should also reference any trade-off analyses conducted. These can either be resource use versus productivity or system conflicts.
There are several constraints that you can list in your system design document. These may be imposed by the hardware, software and end-user environment, interoperability, interface and data repository, security and distribution requirements, network communications, and memory card capacity limitations.
All in all, be sure to provide a detailed list of constraints when writing your system design document.
3. Discuss the Logical Architecture
The third step in coming up with an effective system design document is to discuss the logical architecture of the system. You should break this down into three parts to include the hardware, application and communication architecture.
Under the hardware architecture, describe the entire system hardware and its organization. Ensure that you include a conclusive list of all the hardware components and provide a brief description. You should also include diagrams that show their connectivity and even use subsections for each subsystem where necessary.
Under the application architecture, you should discuss the software build. Therefore, just like in the previous section, focus on the overall software design and organization. Include a conclusive list of the software modules, computer languages, and any programming computer-aided software engineering tools. Also, describe the function of every item on your list.
We advise that you use structured organization diagrams when describing the system software to break down the different segmentation levels. Also, ensure that all the features in these diagrams have reference numbers and names.
These diagrams should provide the physical process and data flow related to the FRD logical process and data flow by mapping to the FRD data flow diagrams.
Under communication architecture, the last section under logical architecture, you should discuss the internal communications build. Therefore, discuss all the communications within the system, such as the LANs and buses.
Be sure to include some of the communications architecture to be implemented, which may be the X.25 or token ring. We also advise that you include a diagram informing the intended audience about the communication paths between the system and subsystem modules. Feel free to include subsections where necessary.
4. Discuss the Physical Architecture
When writing your report, the fourth part should be dedicated to your network architecture. Be as exhaustive as you can and ensure that you cover everything regarding the physical architecture of the system.
5. Discuss the Data Model
You will discuss this in two parts. The first part should discuss the database management system files and the second, the non-database management system files. It would help if you liaised with the Database Administrator to prepare this section successfully.
Make sure that you reveal the final design of all the database and non-database management system files. You should also provide an exhaustive data dictionary capturing the element name, type, length, validation rules, data satires, aliases and description.
The first subsection is the database management system files, including the appropriate diagram and description. Ensure that you capture the refined logical model, which can be done in normalized table layouts, entity-relationship diagrams and any other applicable design information.
Also include a physical description of the DBMS schemas, sub-schemas, records and any other relevant information, as well as the access methods open to users or the intended audience. Ensure that you offer an estimate of the DBMS file size and the volume of data inside the files.
Lastly, define the update frequency of the database files, tables, views, areas and records, which should help you estimate and record the number of transactions for an online transaction-based system database.
The second section under the data model is the non-database management file system. Under this, you are expected to describe all the non-DBMs and outline their usage. Ensure that you identify the record structures, keys and reference data elements within these records.
Also, be sure to define the record length, file access method, and estimate the file size or data within the file. You should also define the update frequency of the file, and just like in the previous section, provide an estimated number of transactions per unit time if the file is part of an online-based system.
6. Discuss the Detailed Design
You should break this into three parts: hardware, application and communication detailed design. The essence of this section is to furnish the system development team with the information needed for building and integrating the hardware components, software modules and bridge a connection between these for a final functional product.
Under the hardware detailed design sub-section, be sure to give detailed information regarding individual component requirements to help you build and procure all the system hardware. However, for extensive component documentation, be sure to use an appendix or even reference a separate document.
Also include additional diagrams and information where applicable to provide an adequate description of every component and its functions. Ensure that you follow the industry-standard component specification and include appropriate item names to identify a specific vendor.
Ensure that you include the following information where applicable: power input requirements, connector specifications, cable type and length, user interfaces, monitor resolution, storage and processor requirements and a graphical representation detailing the number of hardware items.
Under the application detailed design, you will be discussing the software detailed design. Offer enough information about logic and the necessary data to write the source code for all the modules in the system. You can provide additional diagrams and information to describe every module, functionality and hierarchy. Ensure that you include any information that will shed more light on the module designs.
Under the last subsection, discuss the communication detailed design. You should provide enough information about the communication requirements for building or procuring the communication components of the system. Under this, be sure to include the number of servers and clients in each area network, specifications for the bus timing requirements and control, the data formats exchanged between components and the LAN topology.
7. Discuss the External Interface Design
As the name suggests, external systems are not found within the scope of the system under development. Here, you should describe the electronic interfaces while emphasizing the view of the system under development.
Be sure to divide this part into two subsections: the interface architecture and the interface detailed design. Under the interface architecture, describe the interfaces between the system being developed and other systems. These can either be batch transfers and queries. You can also provide succinct information through diagrams, capturing the communication paths between the system and other subsystems.
Under the interface detailed design, provide information about the requirements to format, transmit and receive data across the interface accurately. You can include the query and response descriptions, formats for error reports. Specifications for handshaking protocols between the two systems and the data format requirements, where necessary.
8. Discuss the Graphical User Interface
Under this, you should discuss the detailed design of the system and the subsystem input and output applicable to the user. This should be divided into four subsections, the interface design rules, inputs, outputs and navigation hierarchy.
After discussing the interface design rules, focus on the input. Here, you should capture all the input media used by an operator to feed information to the system. You can include optical character readers and bar scanners. Ensure that you also include the edit criteria for the data elements and address data entry controls to prevent edit bypassing.
Under outputs, you should describe the system output design used by the operator. These include reports, data display screens and query results. Ensure that you identify codes and names for reports, describe the purpose of the output, report distribution requirements, and describe any security considerations and access restrictions.
The last sub-section under this is the navigation hierarchy, where you should talk about the screen and its design.
9. Discuss the System Integrity Controls
The last part of the system design document is system integrity control. Remember, sensitive systems use information that they cannot afford to lose, misuse, modify or permit unauthorized access. That could affect how state programs behave and present a breach of privacy.
Therefore, specifications should be developed for certain levels of controls, such as internal security, audit procedures, application audit trails, standard tables, verification processes guiding addition, deletions, and critical data updates.
Conclusion
These nine steps should guide you in writing a system design document. Ensure that you offer as detailed information as possible.
Click here to download System Design Document Template.
