Markdown System Design Template for Japanese-Style Documents

Copy a structured Markdown system design template with document metadata, revision history, requirements, architecture, operations, risks, and open questions.

Why manage system designs in Markdown

Markdown works well with Git diffs, pull-request review, and repeatable publishing. Japanese business documents often require more than technical prose: document IDs, version, author, approval state, revision history, scope, operations, and unresolved decisions. A template prevents these areas from disappearing between projects.

Use the following as a high-level design starting point. Delete sections that truly do not apply, but state “Out of scope” with a reason when omission could be misunderstood.

Copyable system design template

# System High-Level Design

## Document information
| Field | Value |
|---|---|
| Document ID | SYS-BD-001 |
| Version | 1.0 |
| Date | YYYY-MM-DD |
| Author | Team and name |
| Approver | Team and name |
| Status | Draft / Review / Approved |

## Revision history
| Version | Date | Change | Author |
|---|---|---|---|
| 0.1 | YYYY-MM-DD | Initial draft | Name |

## Overview
### Background
[Why the system is needed]
### Goals
[Business and technical outcomes]
### Audience
[PM, engineering, operations]

## Scope
### Included
- [Included business process or feature]
### Excluded
- [Excluded area and reason]

## Terms and abbreviations
| Term | Definition |
|---|---|
| [Term] | [Definition] |

## Assumptions and constraints
- [Environment]
- [Budget or deadline]
- [Legacy-system constraint]

## System architecture
### Context and components
[Diagram and explanation]
### Component list
| ID | Name | Responsibility | Owner |
|---|---|---|---|
| CMP-01 | [Name] | [Role] | [Team] |

## Functional design
### Feature list
| ID | Feature | Summary | Priority |
|---|---|---|---|
| F-001 | [Name] | [Summary] | Must |
### Key flows
[Happy paths, failures, and actors]

## Data design
### Major data
| ID | Data | Purpose | Retention |
|---|---|---|---|
| D-001 | [Name] | [Purpose] | [Period] |
### Data exchange
[Source, destination, frequency, format]

## External interfaces
| ID | System | Method | Timing |
|---|---|---|---|
| IF-001 | [System] | REST / Batch | [Condition] |

## Non-functional requirements
### Performance and capacity
[Response, concurrency, data volume]
### Availability and recovery
[Hours, RTO, backup]
### Security
[Authentication, authorization, encryption, audit]
### Operations and monitoring
[Signals, alerts, recurring work, support]

## Migration and release
[Data, procedure, rollback, decision criteria]

## Test strategy
[Scope, environment, completion, responsibilities]

## Risks
| ID | Risk | Impact | Response |
|---|---|---|---|
| R-001 | [Risk] | [Impact] | [Mitigation] |

## Open questions
| ID | Question | Owner | Due date |
|---|---|---|---|
| Q-001 | [Question] | [Owner] | YYYY-MM-DD |

## References
- [Requirements](URL)

Treat metadata as part of the design

A filename alone does not prove which PDF is approved after files are copied. Keep version, date, status, and ownership in the cover and body, and connect them to Git tags or approval records. Record changes that affect reader decisions rather than every typo.

Keep tables concise

Tables are useful for inventories and comparisons, not long explanations. Move rationale, failure behavior, and exceptions into prose below a table. Four columns is a practical target for A4 portrait. Replace visible long URLs with labels and divide a table that exceeds one page.

“Avoid break inside table” works for short tables only. A protected table taller than the page creates empty space or unstable pagination.

Add architecture diagrams with Mermaid

```mermaid
flowchart LR
  User --> Web
  Web --> API
  API --> DB[(Database)]
  API --> External[External service]
```

Explain responsibilities, data, and failure behavior in prose as well. Split a wide architecture into an overview and focused details rather than shrinking labels until they are unreadable. For export steps and tips on keeping diagrams legible in print, see How to Export Mermaid Diagrams from Markdown to PDF.

Export the design as PDF

Load the .md file into a PDF workflow that supports a cover and generated TOC. Add the document name, organization, date, and revision. Use H2 headings as primary contents entries and H3 headings as supporting hierarchy, then verify starting-page references in the saved PDF.

Apply document-wide margins, numbering, and page background through print CSS or converter settings. Use break-before and break-inside selectively around chapters, tables, code, and diagrams. Name the exported PDF with the title, date, and revision, and keep that revision consistent with the document body. The same delivery workflow works for minutes, specs, and other paperwork—see Markdown for Business Documents: Minutes, Specs, Resumes & PDFs.

Review checklist

Scope and exclusions are explicit.
Requirements, features, and tests are traceable.
Every open question has an owner and date.
Tables do not contain paragraphs of prose.
Diagrams agree with the written design.
Security and operations are complete.
Cover, body, and filename versions match.
TOC references and page numbers were checked in the saved PDF.

FAQ

Does every project need every section?

No. Merge or remove sections for small projects, but do not silently omit security, operations, risks, or open questions. State why a subject is out of scope.

Can this become a detailed design?

Reuse metadata and common sections, then deepen each feature into inputs, processing, outputs, failures, authorization, and logging. Preserve links back to high-level requirement IDs.

What if the recipient needs Word?

Convert the same source to docx with Pandoc or another compatible converter when recipients need to edit it. Use PDF for an approved, fixed snapshot.

Try the system design template as PDF