
在编写一些重要文档时需要插入一些示意图，如统计图、UML、流程图等，经常遇到 Markdown 图片和文本分离的问题，在 Markdown 中管理图片是比较麻烦的事，尤其是像统计图、UML 等需要频繁更新、版本管理的图片。

对于这类问题，我推荐的方案是 TTD (text-to-diagram). 现在有很多开源的免费的 TTD Generator，如 [Mermaid.js](https://mermaid.js.org/intro/)、[PlantUML](https://plantuml.com/en) 和 [GraphViz](https://graphviz.org/). 它们允许你使用文本形式的 DSL 代码去绘制图形，一般来说一份代码对应一种图像，非常利于文档中的插图。 [你可以在这里去体验它们](https://text-to-diagram.com/).

在这里我主要讨论 PlantUML、Graphviz 两种插件以及对应的不同情景。

## PlantUML

PlantUML 是老牌的、工业级的 UML 绘图工具，提供的 UML 也是最全的，很多教科书、学术论文等专业场景都采用的 PlantUML。因为“大而全”，所以它的学习曲线较为陡峭，文档内容也非常多，需要仔细研读。

[这是 PlantUML 的在线体验地址](https://www.plantuml.com/plantuml/)，以及[文档地址](https://plantuml.com/)。

我们写一个简单的图书馆系统的用例图，输入以下 PlantUML 代码：

```plaintext
@startuml
left to right direction

actor 读者 as Reader
actor 图书管理员 as Librarian

rectangle 图书馆管理系统 {
  usecase "搜索图书" as UC1
  usecase "借阅图书" as UC2
  usecase "归还图书" as UC3
  usecase "管理图书信息" as UC4
  usecase "生成借阅报告" as UC5

  Reader --> UC1
  Reader --> UC2
  Reader --> UC3

  Librarian --> UC4
  Librarian --> UC5

  UC2 .> UC1 : <<include>>  // 借阅前需搜索
  UC3 .> UC1 : <<include>>  // 归还前需搜索
  UC5 .> UC2 : <<extend>>   // 报告可扩展借阅细节
}
@enduml
```

它生成的用例图如下：

```plantuml
@startuml
left to right direction
actor 读者 as Reader
actor 图书管理员 as Librarian
rectangle 图书馆管理系统 {
  usecase "搜索图书" as UC1
  usecase "借阅图书" as UC2
  usecase "归还图书" as UC3
  usecase "管理图书信息" as UC4
  usecase "生成借阅报告" as UC5

  Reader --> UC1
  Reader --> UC2
  Reader --> UC3

  Librarian --> UC4
  Librarian --> UC5

  UC2 .> UC1 : <<include>>  // 借阅前需搜索
  UC3 .> UC1 : <<include>>  // 归还前需搜索
  UC5 .> UC2 : <<extend>>   // 报告可扩展借阅细节
}
@enduml
```

它生成的图像 UI 都有上个世纪的风格，比较适合对样貌美观性不高的场景，如教科书、论文等，好在可以自己选择主题。

但是 PlantUML 是基于 Java 编写的，运行它需要提供 Java 运行环境并放在后端中运行。但官方也把它打包成了一个 **图像生成的 Web 服务器**，把它部署在自己的服务器上就可以了。

使用 PlantUML Web 服务器的方法很简单，你只需要把要生成的 PlantUML 代码压缩、编码成 URL 参数，再传递给服务器即可。

就比如上面的 PlantUML，把代码编码，生成

```
VPBBIiD058RtWRp3eVjQ.....
```

然后就可以生成引用图片的 URL 了

```
![](https://www.plantuml.com/plantuml/VPBBIiD058RtWRp3eVjQ.....)
```

### VSCode 集成

PlantUML 有[官方 VSCode 插件](https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml)，可以添加对其相关代码和语言的支持，当然也可以在 Markdown 预览视图中添加图像预览支持，只需要在 markdown 中编写代码，在预览中自动生成图像，就像这样。

![](https://github.com/qjebbs/vscode-plantuml/raw/master/images/markdown_demo.png)

### Unified.js 集成

如果需要和开源文档处理器 unified.js 集成，我编写了一个 remark 插件 [remark-refer-plantuml](https://github.com/PrinOrange/remark-refer-plantuml)，可以在 Markdown 文档语法树中自动完成识别、编码并替换成图像 URL 引用的这一过程。

## Graphviz

[Graphviz](https://gitlab.com/graphviz/graphviz) 是一个基础插图生成库，使用 DSL 来定义、生成图像，用算法自动排列节点和边，特别适合生成复杂的图表。

比如，用 Graphviz 写一个红黑树：

```plaintext
digraph RedBlackTree {
    node [shape=circle, style=filled, fontcolor=white];

    10 [fillcolor=black];
    5 [fillcolor=red];
    15 [fillcolor=red];
    3 [fillcolor=black];
    7 [fillcolor=black];
    12 [fillcolor=black];
    18 [fillcolor=black];

    10 -> 5;
    10 -> 15;
    5 -> 3;
    5 -> 7;
    15 -> 12;
    15 -> 18;
}
```

渲染效果图如下：

```graphviz-dot
digraph RedBlackTree {
    node [shape=circle, style=filled, fontcolor=white];

    10 [fillcolor=black];
    5 [fillcolor=red];
    15 [fillcolor=red];
    3 [fillcolor=black];
    7 [fillcolor=black];
    12 [fillcolor=black];
    18 [fillcolor=black];
    
    10 -> 5;
    10 -> 15;
    5 -> 3;
    5 -> 7;
    15 -> 12;
    15 -> 18;
}
```

或者写一个归并排序分治算法的流程示意图

```dot
digraph MergeSort {
    node [shape=plaintext];

    // 初始数组
    array [label="4  2  5  1  3", shape=box];

    // 递归拆分过程
    split1 [label="4  2  5   |   1  3", shape=box];
    split2_1 [label="4  2  |  5", shape=box];
    split2_2 [label="1  |  3", shape=box];
    split3_1 [label="4  |  2", shape=box];

    // 归并过程
    merge1_1 [label="2  4", shape=box];
    merge1_2 [label="1  3", shape=box];
    merge2 [label="2  4  5", shape=box];
    merge3 [label="1  2  3  4  5", shape=box];

    // 连接拆分过程
    array -> split1;
    split1 -> split2_1;
    split1 -> split2_2;
    split2_1 -> split3_1;
    split2_1 -> "5";
    split2_2 -> "1";
    split2_2 -> "3";
    split3_1 -> "4";
    split3_1 -> "2";

    // 连接合并过程
    "4" -> merge1_1;
    "2" -> merge1_1;
    "1" -> merge1_2;
    "3" -> merge1_2;
    merge1_1 -> merge2;
    "5" -> merge2;
    merge1_2 -> merge3;
    merge2 -> merge3;
}
```

Graphviz 的绘图功能也十分强大，根据代码生成 SVG 图像，但由于是底层库，对样式、布局算法等细节还需要自己手动完成，如果有自定义需求，通常需要二次开发。

Graphviz 是使用 C、C++ 语言进行开发的。也可以编译成 WASM，允许你直接在浏览器前端、Node.js 中使用。WASM 包有 [Viz.js](https://github.com/mdaines/viz-js)、[hpcc-js-wasm](https://github.com/hpcc-systems/hpcc-js-wasm) 等。

### VSCode 集成

VSCode 有对 Graphviz 语言的插件。不过，对在 VSCode Markdown 中预览视图的支持的插件不多，且缺乏维护。

所以我写了一个 VSCode 插件：[Markdown Graphviz Preview](https://marketplace.visualstudio.com/items?itemName=PrinOrange.markdown-graphviz-preview).

![](https://image-assets.dreams.plus/images202503031335435.png)

### Unified.js 集成

同样，我也写了一个 rehype 插件 [rehype-graphviz-diagram](https://www.npmjs.com/package/rehype-graphviz-diagram)，可以与 unified.js 文档处理集成。


在 Markdown 工程写作中，经常会有插入 UML，流程图，架构图等示意图的需求。本文推荐两种工具以及对应的 Markdown 处理库、Visual Studio Code Markdown 扩展插件。

工程写作：Markdown 插入示意图


I have tried to do technical writing in English on intend since 2022, when I made my mind of putting wheels on my shoulder for English study. Actually I have tried my English writing skill on intend by this way for make my language level better improved. And during these years I have experienced many challenges and troubles in conquering English.

The first one is vocabulary size. I allocated many of my vigors on expanding vocabularies and accumulated English expression particles in studying and reading. But soon I realized that reading technical text and literature text are two different realm logic.

The technical text are legible with perspicuous grammar syntax structure, and that's why I could read many of opensource project documents without any difficulties. The only challenge is reserve of terms and jargons. That's why do we need specialized professional English, for English has been contaminated by more loan words, and there are more amorphous word ideographic stemmer rules in each terms. To be honest I have complain about English more on this problem, it erects human-made thresholds among variable industries. The topic seems too be far-fetched. Let's go back to the technical writing. The another problem is English term are highly specialized, that is to say polysemy may lead to ambiguity if without any context details. For example, the word *layer* has distinguish meanings in software development and stratum geology. Also non-native speakers tend to confuse synonyms (e.g., "accuracy" vs. "precision") and need to rely on terminology databases or industry standards (e.g., IEEE Standard Glossary).

For special target portrayed, the passive voice in English is frequently used in technical writing (e.g. "The experiment was conducted..."). Non-native speakers may overuse the active voice, which affects objectivity. Complex sentences (e.g. conditional clauses, participle structures) are prone to grammatical errors. The concise principle of technical writing should be followed (e.g. IEEE recommends using short sentences).

Improper use of logical adjunction-connectors ("therefore", "however") between paragraphs can weaken the chain of reasoning. The English technical writing needs rigorousity suits for logical deduction chains. But for non-native speakers, the English adjunction connector words are too far exquisite to comprehend them easily.

Here, I found a pretty worth reading book titled *Science Research Writing for Non-native speakers of English*. [Here is the download link](https://z-library.sk/book/25451495/4d36ea/science-research-writing-for-native-and-nonnative-speakers-of-english.html). It's a practical guide designed to help researchers and students whose first language is not English master the conventions of scientific writing in English. Authored by Hilary Glasman-Deal, the book focuses on the structure, style, and clarity required in academic research papers. It systematically breaks down each section of a scientific manuscript—Introduction, Methods, Results, Discussion (IMRaD), and Abstract—providing clear templates, annotated examples, and phrase-level guidance.

Here is the table of contents:

![](https://image-assets.dreams.plus/images202502122348927.png)

Based on problem mentioned above, I have made a plan for training technical writing in English. This 12-week plan is designed to systematically improve scientific writing skills for technical writing. Adjust intensity based on schedule.

**Phase 1: Foundations (Weeks 1–3)**  
**Goal**: Master structure, grammar basics, and discipline-specific vocabulary.  

1. **Reverse-Engineer Papers**  
   - Select 3 high-impact papers in your field (e.g., from *Nature* or your target journal).  
   - Annotate each IMRaD section: Highlight how hypotheses/results are framed, transitions between paragraphs, and verb tenses.  
   - Create a "phrase bank" of recurring patterns (e.g., "Our data suggest..." in Discussions).  

2. **Grammar & Style Drills**  
   - Daily: Complete 1–2 exercises from *Science Research Writing for Non-Native Speakers* (e.g., tense consistency in Methods).  
   - Use *Academic Phrasebank* (University of Manchester) to practice hedging/emphatic language.  
   - Tools: Enable "Technical Writing" mode in Grammarly; analyze suggestions for passive voice/precision.  

3. **Vocabulary Building**  
   - Build a glossary of 50+ field-specific terms using *Elsevier’s Dictionary of Technical Terms*.  
   - Practice synonym differentiation (e.g., "demonstrate" vs. "indicate") via quizzes on *Quizlet*.  

**Phase 2: Drafting & Precision (Weeks 4–6)**  
**Goal**: Write structured drafts with clear logic and technical accuracy.  

1. **Section-by-Section Practice**  
   - **Abstract**: Write 10 one-sentence summaries of existing papers, then expand to 250-word abstracts.  
   - **Methods**: Describe a lab procedure twice: once in active voice (blog style), once in passive voice (journal style).  
   - **Results**: Convert raw data (graphs/tables) into 3 versions: overly detailed, too vague, and Goldilocks-level.  

2. **Peer Simulation**  
   - Join *r/AskAcademia* or *ResearchGate* to share drafts for feedback.  
   - Use the "Three Layers" editing technique:  
     - Layer 1: Logic flow (Does each paragraph answer "So what?").  
     - Layer 2: Technical accuracy (Verify units, abbreviations, citations).  
     - Layer 3: Language (Prepositions/articles, conciseness).  

3. **Tools Deep Dive**  
   - Learn LaTeX basics (Overleaf tutorials) for equations/formatting.  
   - Run drafts through *Hemingway Editor* to eliminate "Very Hard to Read" sentences.  

**Ongoing Habits:**  

- **Weekly**: Critique 1 poorly written paper (e.g., retracted papers on *Retraction Watch*) to recognize red flags.  
- **Monthly**: Attend 1 virtual workshop (e.g., *ACS Webinars* on writing).  
- **Toolkit**: Maintain a "Writing Swipe File" (YuQue/Notion) for brilliant sentences/structures you encounter.  

Hope for good progress.


I have tried to do technical writing in English since 2022. And now I have came up with a further plan.

About Technical Writing in English.


This issue can be seen as a classic case of historical inertia combined with outdated reforms in the education system. This encapsulates the core of the problem.

Frankly, I find it difficult to tolerate the myriad justifications people offer to defend this situation. It is merely a residual consequence of the glacial pace of educational reform, yet some have framed it as "developing logical thinking" or claimed that "university isn't a training camp." Such arguments are utterly untenable.

In reality, even if computer science majors studied more mathematics instead of physics, it would be far more beneficial.

Computer science fundamentally diverges from traditional engineering disciplines such as civil engineering, mechanical engineering, electronic engineering, and chemical engineering. These traditional fields are rooted in physics, whereas computer science is deeply grounded in mathematics.

Traditional engineering disciplines primarily engage with the physical world. Their foundations lie in natural sciences, particularly physics, and they boast histories spanning decades, if not centuries. The primary focus of these disciplines is the transformation of the physical realm.

Consider this: as a mechanical engineering major, it is inconceivable to bypass the study of mechanics—how else would you design gears? If you are in precision instrumentation, knowledge of optics and electronics is indispensable for designing sensors. For chemical engineering students, quantum mechanics and thermodynamics are fundamental to understanding molecular interactions. Similarly, hydraulic engineering requires mastery of fluid mechanics.

Each traditional engineering discipline is built upon natural sciences like physics, dedicated to leveraging these principles to reshape the material world.

In stark contrast, computer science follows an entirely distinct trajectory. It is a "formal science," entirely man-made, with most of its concepts abstracted directly from mathematics.

Modern computer science theory originated with Alan Turing, whose work on computability theory employed pure mathematical constructs to define the concept of a "computer." These theoretical foundations were later implemented to create various types of computing systems.

Computer science, at its core, studies theoretical frameworks. While engineers apply these frameworks to design chips and systems, the discipline itself focuses on abstract structures and models rather than the tangible, physical world.

Formal sciences—such as mathematics, logic, and computer science—emphasize abstract, logical constructs instead of physical phenomena. They rely on deductive reasoning and logical proofs rather than empirical observation, which aligns computer science closely with mathematics.

For instance, many foundational concepts in computer science, such as Turing machines, operating system models, and the Von Neumann architecture, are mathematical abstractions. These constructs do not exist in nature; they are products of human ingenuity.

Even programming concepts such as functions, pointers, parameters, and operators—or areas like complexity analysis—are rooted in mathematical models. Algorithm design exemplifies this reliance on mathematical abstraction.

So, what justification exists for requiring computer science majors to study physics? Will they be calculating the forces involved in moving servers? Or perhaps determining the melting point of silicon to fabricate CPUs?

Let us be candid: computer science is fundamentally a repository of mathematical abstractions. This alignment with mathematics is entirely unsurprising, given the discipline's origins.

And for those who argue, "We study electronics to design circuits for CPUs," it is crucial to clarify: digital circuits and logic gates are mathematical abstractions as well. The physical implementation of chips falls under the domain of electronic engineering, not computer science. The role of computer science is to provide the models, theories, and blueprints, while other fields handle physical realization.

Furthermore, most computer science graduates today pursue careers in software development. It is unrealistic to assume they are designing CPUs.

In China, computer science was only formalized as a university discipline in the 1980s, following the reinstatement of the national college entrance exams. However, the theoretical foundations of computer science had already been established during World War II. By the time China integrated it into its educational system, we were already lagging behind Western nations by no less than half a century.

During that era, computers were a rarity in China, and expertise in teaching the subject was even scarcer. Lacking domestic models to emulate, we resorted to copying. Since physics was a staple of other STEM fields, it was incorporated into computer science curricula as well.

And yet, we remain entrenched in these antiquated practices. Despite nearly four decades, our approach to computer science education continues to stagnate. For example, certain universities still teach C++ using VC6, a tool that is unequivocally obsolete by contemporary standards.

In conclusion, the shortcomings of computer science education in China can be attributed to historical inertia and outdated reforms. Unlike traditional engineering disciplines rooted in physics, computer science is grounded in mathematics and focuses on abstract models. The inclusion of subjects like physics in the curriculum reflects a failure to adapt to the unique nature and practical demands of this field.


China's computer science education is outdated, often including irrelevant subjects like physics, due to historical and systemic inertia.

Should Computer Science Majors Learn College Physics


In the United States, the date format is uniquely distinctive and stands out globally. Unlike the European "small to large" DMY format or the East Asian "large to small" YMD format, the U.S. uses MDY. Moreover, unlike other Europeans who prefer pure numeric date formats, Americans use a semi-numeric, semi-English format: English month + numeric date + numeric year. For example, today is November 27, 2024. While a British person might write it as 27/11/2024, an American would write it as November 27, 2024!

Below is a map of date formats around the world:

![](https://image-assets.dreams.plus/images20241128101343.webp)

In the map, blue areas represent DMY, yellow areas represent YMD, red areas use a mix of DMY and MDY, green areas use a mix of DMY and YMD, and pink areas exclusively use MDY. The only country that uses this date format is the United States.

A British author once complained American written form, and wrote this on his book.
> “Most British people write the day first, followed by the month. Businesspeople and older women still insist on putting the month first.” \
> —— _Have His Carcase_, by Dorothy Leigh Sayers

I am genuinely puzzled by the logic behind the American date format. Many former British colonies or Commonwealth countries have adopted the British DMY format. But why didn't the United States, once a British colony heavily influenced by British culture, inherit the DMY format?

In fact, the American insistence on their date format has led to some amusing anecdotes. For instance, a British woman and an American man planned a date and wrote "10/12/1997" in their letters. However, they never met. Why? Because the American man understood it as October 12, while the British woman understood it as December 10!

If the world only had YMD and DMY formats, even when Asians and Westerners read each other's texts, there would be no ambiguity.

For example, dates like "2024-11-11" and "11-11-2024" can be easily understood by looking at the position of the year, allowing one to quickly determine the date format and identify the corresponding month and day. The world would be a much better place.

However, the problem lies in the strong influence of the United States in computer science and technology, which has forced their culture, including the anti-human MDY date format, onto the world, including Europe.

If you encounter an English text with a date like "11/11/2024" and cannot determine whether it was written by an American or a British person, how would you interpret it?

As a result, many English-speaking countries, including several European nations, have had to compromise: when dates are ambiguous, the month should be written in abbreviated form. For example, the British would write the above date as 11 November, 2024, or 11 Nov. 2024.

Thus, the world is now caught in a three-way battle between MDY, YMD, and DMY.

The origins of the YMD and DMY formats reflect the long-term practical needs of Eastern and Western civilizations. The reasons for these differences are varied and inconclusive, but there are two plausible explanations from cultural needs and cognitive linguistics.

The first explanation is based on cultural needs.

For a long time, the Chinese did not adopt the Western Gregorian calendar but used the era name system. Era names held significant political importance in ancient China, reflecting the will of the state and the emperor. After Emperor Wu of Han, official documents often placed the era name at the beginning to show its importance. China, being an agricultural society, developed the lunar calendar, where agricultural activities were often organized by months for planting, cultivating, and harvesting. Hence, the Chinese prioritized the year and month. Other East Asian countries like Korea, Japan, and Mongolia were also influenced by the Chinese lunar calendar.

Europeans, on the other hand, had a different approach. During the Middle Ages, Europe was deeply religious, and Europeans frequently participated in religious activities such as Sundays and sermon days. Church activities emphasized specific dates of holidays and religious events, with months being secondary information and years changing less frequently, thus placed last. For example: "Die 31 mensis Decembris anno Domini 2024" (December 31, 2024). This tradition of prioritizing the "day" has continued in many European countries, influencing their date formats.

The second explanation comes from cognitive linguistics.

From a linguistic perspective, the Western DMY format is used because European languages generally follow a logical sequence from specific to abstract, with the date as a modifier expressed first, close to the core words of month and year. In many Indo-European languages, modifiers (such as specific dates or temporal features) usually precede the main information. Western address formats also share this characteristic, starting with the house number and street, followed by the city, state, or province. This format aligns with the European linguistic habit of "modifiers being close to the modified object" and fits their cultural emphasis on logic and linear time flow. Chinese, using a large-to-small logic (year → month → day), emphasizes the progressive relationship of time, aligning with the Chinese narrative structure of "background to specifics."

In my opinion, the best date format should be one that is friendly to both humans and computers, which is the YMD format popular in East Asian countries. YMD is more intuitive for humans and most convenient for organizing documents.

While the differences between YMD and DMY can be explained from various angles, what is the logic behind the American MDY format? What is the rationale for using MDY?

After extensive online research, I have not found a concrete reason.

I strongly suspect that some American just came up with this date format on a whim.

Since most languages (like Chinese and English) are read from left to right, imagine you need to sort a pile of documents by date. When you see a date like "20241111," you can easily scan the numbers 2-0-2-4-1-1-1-1 in sequence, quickly identifying the year and month prefix, and categorize it into a "broad range" for easier sorting. However, if the date format is the British DMY, like "12072024," you need to interrupt your reading flow, start scanning from the end (4-2-0-2), then correct the order to "2-0-2-4" to identify the year, and then scan "7-0," correcting it to "0-7" to identify July. Thus, when scanning a DMY date, extracting the year and month requires changing direction four times. While manageable in the short term, it becomes a significant mental burden with large workloads, greatly increasing the chance of errors due to carelessness.

The YMD format is also very computer-friendly. YMD dates can be directly sorted in computers, as the string format "2024-07-12" is sequentially encoded, making dictionary sorting straightforward.

Imagine you have two files:

```plaintext
2024-11-12-document1.docx
2024-12-07-document2.docx
```

With the date format prefix, the former file name will always have a higher dictionary order than the latter, allowing file explorers to sort by date directly using the file names.

Numeric dates like "20240712" also make it easy to compare two dates using simple computer comparison operators like `>` and `<`, without needing additional processing.

These advantages are not present in the DMY format.

American stubbornness is not limited to date formats; their measurement standards are also a mess. For example, Fahrenheit and imperial units (miles, inches, feet, gallons, ounces, etc.). The imperial system originated during the Roman Empire in Europe and has long been a confusing mess with no fixed standards, changing over different historical periods. It wasn't until the Middle Ages that Britain standardized these units.

However, when Britain established the imperial system, there were no strict, standard measurements. For example, an inch was defined as the length of three barleycorns laid end to end, and a foot was the distance from King Edward's nose to his outstretched hand. The problem is, using barleycorns to define an inch means a thousand barleycorns could have a thousand different lengths, and using body parts for length definitions means a thousand people could have a thousand different lengths. It remains a confusing mess.

The long-standing confusion in measurements was only resolved with the development of modern French natural science, leading to the strict definition of the metric system. The metric system uses reproducible physical experiments for definitions, making it much more rigorous than the imperial system.

Thus, today, the entire world, except the United States, uses the metric system. But the U.S. remains an outlier, stubbornly clinging to the imperial tradition under the guise of "cultural heritage" and "preserving freedom and diversity." The American refusal to adopt the metric system is as irrational as the Lilliputians in _Gulliver's Travels_ arguing over which end of an egg to crack. It's truly bizarre.


In the United States, the date format is unique in the world. It is different from the European "small to large" DMY and the East Asian countries' "large to small" YMD. It is actually MDY.

NOTE & BLOG

OTHERS

工程写作：Markdown 插入示意图

About Technical Writing in English.

Should Computer Science Majors Learn College Physics

Complain on American Date Format