How to Write Good Design Documents

2023-03-09

This article mainly provides some experience and suggestions for readers who need to write software design/development documents.

Reading Prerequisites

• Understand Markdown syntax
• Understand Typora, Sublime Text or VS Code and other editors that facilitate Markdown editing

Target Audience

• Product managers, Project managers who need to write product/function description documents
• Software engineers who need to write basic designs and detailed designs for functions to be developed

1. Software and Document Format Selection

In general, design documents related to software development mostly have the following characteristics:

• No need for particularly flashy styles
• Frequently require modifications
• Mostly plain text except for UI design
• Basic structure and format are largely the same
• Often include code and data that need to be easily copied

Therefore, it is generally recommended that such documents be written in plain text Markdown format.

Markdown uses simple markup syntax to display commonly used features such as headings, lists, highlights, quotations, code blocks, and links. Later, it can also be conveniently exported into HTML, PDF, and other formats.

For more information on Markdown syntax, refer to: https://www.runoob.com/markdown

2. Basic Structure of Design Documents

When writing design documents, they must be written from the perspective of a "new employee" in the company, and no assumptions should be made about what the reader already knows.

Therefore, a design document generally needs to include at least the following sections:

1. A "one-sentence description" title
2. Table of contents
3. Business process
4. Data definition

2.1 "One-Sentence Description" Title

Do not directly use "document" or "design document" as the file name or title.

The file name or title is best described in "one sentence", such as:

• Guance New Event Data Structure and Processing Logic Design
• Guance Cloud Association Processing Logic Design

This way, it reduces the likelihood of file name duplication, and readers can roughly understand the content of the document without opening it.

2.2 Table of Contents

A table of contents should be added to any document, which allows readers to understand the general content of the document during their first reading and makes it easy to quickly look up and jump to specific content.

Using Typora, you can choose "Paragraph / Content Table of Contents" to insert a table of contents.

Using Sublime Text, VS Code, you can use plugins like MarkdownTOC to generate a table of contents.

Different software may have different ways to implement tables of contents, which may not be compatible with each other

2.3 Business Process

Any design document must describe the business process, specifically detailing "what actions the user takes, what processing the system performs, and what happens in the end."

For simple business processes, lists can be used directly, such as:

1. The user enters a username and password, clicks login
2. The system searches for matching users based on the input content
   1. If matched successfully, redirect to the Dashboard page
   2. If matched unsuccessfully, prompt "Incorrect username or password"

For complex business processes, flowcharts can be used to describe them, such as:

Flowcharts can be drawn using ASCII Art, professional flowchart tools, PowerPoint, Keynote, etc.

2.4 Data Definition

All fields, field types, value ranges, and data sources of business entities generated in the business process must be clearly defined.

Assuming there is a business entity called "course", the data definition table is as follows:

Field	Type	Required / Default Value	Description
code	String	Required	Course code, globally unique
name	String	Required	Course name
type	Enum	Required	Course type, possible values: Liberal Arts=liberal, Science=science
seatCount	Integer	Required	Number of seats, range: 0 ~ 100
userId	String	Required	Course creator ID. Automatically filled in upon creation
teachers	Array	Required	Instructor list
teachers[#]	Array	Required	Instructor list element
teachers[#].userId	String	Required	Instructor's user ID
teachers[#].position	Enum	Required	Instructor position, possible values: Speaker=speaker, Assistant=assistant
tags	Array	null	Course tag list
tags[#]	String	Required	Course tag element
extraInfo	Dict	null	Additional information
extraInfo.computerRequired	Boolean	false	Whether a computer is required
extraInfo.outdoorActivityIncluded	Boolean	false	Whether outdoor activities are included

Descriptions in the table should not be too long; for fields requiring complex explanations, a separate subheading should be created for detailed descriptions

Using tables to display field lists makes the structure clearer and less burdensome for readers. Additionally, during writing, it is less likely to miss certain descriptions of fields.

For JSON data, it can also be presented directly in JSON format, such as:

{
    // [Required] Course code, globally unique
    "code": "CLASS-001",
    // [Required] Course name
    "name": "Chinese Language 1",
    // [Required] Course type, possible values: Liberal Arts=`liberal`, Science=`science`
    "type": "liberal",
    // [Required] Number of seats, range: `0 ~ 100`
    "seatCount": 100,
    // [Required] Course creator ID. Automatically filled in upon creation
    "userId": "user-001",
    // [Required] Instructor list
    "teachers": [
        {
            // [Required] Instructor's user ID
            "userId": "user-002",
            // [Required] Instructor position, possible values: Speaker=`speaker`, Assistant=`assistant`
            "position": "speaker"
        },
        {
            "userId": "user-003",
            "position": "assistant"
        }
    ],
    // Course tags, elements are Strings
    "tags": [ "Basic", "Compulsory", "Senior Instructor Lecture" ],
    // Additional information
    "extraInfo": {
        // Whether a computer is required
        "computerRequired": false,
        // Whether outdoor activities are included
        "outdoorActivityIncluded": true
    }
}

When presenting in JSON format, it should be organized into an easily readable indented format

It is recommended to prioritize describing using tables, secondarily using JSON, and providing both table and JSON formats being the best!

3. More Complex Design Documents

For design documents of small systems or individual functional modules, providing the above four basic contents generally meets the needs.

If it is a description of the entire system, or design documents for multiple, complex functional modules, then it is necessary to add more content for explanation.

3.1 Splitting Large System Design Documents

For large system design documents, the documents should be divided into levels:

1. Basic design: describes the overall architecture of the system, but does not involve specific internal details of functions
2. Detailed design: describes specific functional modules, business entities involved in specific functions, processing flows, field definitions, etc.

3.2 Concept Explanations

Concepts and business entities appearing in the document need clear definitions to avoid misunderstandings. For example:

• Course class: refers to course content including materials and textbooks, such as: "Introduction to Cloud Computing"
• Session activity: refers to an activity of a particular course held at a specific time and place, such as: "Introduction to Cloud Computing Shanghai First Session 2021"

And provide examples for clarification. For example:

1. Backend administrators create and enter the "Introduction to Cloud Computing" course (here operating on the "course class")
2. Instructors select "Introduction to Cloud Computing" to start classes according to the schedule and specify the start time (here operating on the "session activity")
3. Students choose cities and times to enroll in already opened courses (here operating on the "session activity")
4. Due to the pandemic, all training sessions in 2020 were canceled (here operating on the "session activity")
5. Cloud computing has become widely accepted, and there is no longer a need to continue offering "Introduction to Cloud Computing," so it is taken off the shelf (here operating on the "course class")

3.3 Architecture Diagrams

Whether for overall system design or the design of a single functional module, architecture diagrams can be attached to help readers understand.

For example: DataFlux Func architecture diagram

For example: DataFlux Func "subscriber" architecture diagram

3.4 Project File Directory

For established projects, on one hand, to allow new hires to quickly grasp the overall project situation, and on the other hand, to standardize subsequent development work, a project file directory can be added for explanation.

For example: DataFlux Func project directory explanation

Directory/File	Description
client/	Front-end code (Vue.js)
server/	Back-end code (Node.js + Express)
worker/	Worker unit code (Python3 + Celery)
db/	Database export files
sdk/	SDK files for calling this system
test/	Automated testing
tool/	Useful small tools for the project
run-server.sh	Back-end service startup script
run-worker.sh	Worker unit startup script
run-beat.sh	Timer startup script
config.yaml	Configuration file (shared by all services)
admin-tool.py	Management tool for employees

3.5 Reference Links

For associated/reference documents mentioned in the document, they should be listed out for quick reference. For example:

• Alibaba Cloud ECS List API Reference Document: https://help.aliyun.com/document_detail/25506.html
• Tencent Cloud CVM List API Reference Document: https://cloud.tencent.com/document/product/213/15728
• AWS EC2 List API Reference Document: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/ec2.html

4. Reasonable Use of Formatting

Reasonably using formatting can help readers understand the content faster and reduce reading burden.

4.1 Titles

Adding hierarchical numbering to each title will make the table of contents clearer and also help readers determine their current reading position instantly.

For instance, this article uses 1., 1.1., 1.1.1. to organize titles by size.

However, note that title hierarchy should not be too deep, generally not exceeding 4 levels is preferable. The smallest level title can consider omitting hierarchical numbering, such as:

1. Overview of Cloud Computing
2. Current Status of Cloud Vendors
        2.1 Domestic
                Alibaba Cloud
                Tencent Cloud
                Huawei Cloud
        2.2 Overseas
                AWS
                Azure
                Oracle

4.2 Points of Attention, Tips

Points that need the reader's attention should use a unified emphasis format, such as:

Note: All points of attention should appear in the "Note: XXX" format

Or other special formats supported by the documentation system

Similarly, incidental tips should also use a unified format, such as:

Tip: All tips should appear in the "Tip: XXX" format

Or other special formats supported by the documentation system

4.3 Lists

When listing content, lists should be used to present the information, such as:

• Alibaba Cloud
• Tencent Cloud
• AWS

You can also attach brief descriptions, such as:

• Alibaba Cloud: largest domestic market share
• Tencent Cloud: widely used in gaming industry
• AWS: largest overseas market share

4.4 Links

When adding official websites or entry links, they can be displayed directly as clickable URL addresses, such as:

https://help.guance.com/

If the link refers to specific content, multiple links are listed, or the URL address is very long, the link should be annotated with text descriptions, such as:

Guance Documentation / Release Notes (2023)

Guance Documentation / Quick Start

5. Precautions During Document Writing

Controlling some details during the document writing process can significantly improve document quality and reduce the burden on readers.

5.1 Consistency in Word Choice and Descriptions

Consistent word choice throughout not only facilitates searching but also enhances reading efficiency.

Correct example:

Alibaba Cloud is the largest domestic cloud vendor in terms of market share, and the majority of enterprise users choose to conduct business on Alibaba Cloud.
At the same time, Alibaba Cloud offers the most extensive range of products among domestic cloud vendors.

Name: string, required, length range 2～4
School: string, required, length range 1～10
Age: positive integer, required, value range 1～99
Height: positive integer, optional, value range 1～200

Incorrect example:

aliyun is the largest domestic cloud vendor in terms of market share, and the majority of enterprise users choose to conduct business on Alibaba Cloud.
At the same time, Alibaba Cloud’s products are the most extensive among domestic cloud platforms.

Name: string, required, shortest 2 characters, longest 4 characters
School: required, str, length range 1～10
Age: positive integer, value range 1～99, required
Height: optional, positive integer greater than 0, maximum 200

5.2 Handling Mixed Chinese-English Text

When mixing Chinese and English, adding spaces before and after English words makes it easier to read.

• [Recommended] Spaces before and after English: Alibaba Cloud's ECS is one of its core products.
• No spaces before and after English: Alibaba Cloud'sECSisoneofitscoreproducts.

When the mixed content is a field name, use code formatting to display it.

• [Recommended] Field names use code formatting: The InstanceId field returned by the interface is globally unique.
• Field names do not use code formatting: The InstanceId field returned by the interface is globally unique.

When involving keys, use key formatting to display them.

• [Recommended] Use key formatting: Press CTRL + S shortcut key to save.
• Do not use key formatting: Press CTRL + S shortcut key to save.

5.3 Attach Code Examples When Necessary

Sometimes, lengthy explanations are less intuitive than a complete example, such as:

Write the following code in DataFlux Func to implement an addition function.

@DFF.API('Sum of Two Numbers')
def plus(x, y):
    '''
    x, y automatically convert to floating-point numbers
    '''
    return float(x) + float(y)

6. Management and Distribution of Documents

After completing the document, if conditions permit, you can choose to manage it using git, or use ordinary cloud storage for management.

When distributing documents via DingTalk groups, you can use Typora's export to PDF function. This allows people without Markdown editors to preview and read directly within DingTalk.

Postscript

Good design documents can reduce communication barriers and also help new hires quickly understand the overall project situation.

The methods and designs mentioned in this article cannot possibly fit all systems, here only as a reference recommendation to everyone, hoping to provide useful help.