<-- home

技术文档的最佳实践

October 16, 2023

other

技术文档的最佳实践

编写技术文档时开发过程中常见的需求。一份好的开发文档可以有很多作用：

帮助使用者快速入门；
指导开发者进行项目编译；
为开发者做维护进行指南等。

痛点

传统技术文档使用 Word 或者一些在线工具或多或少存在了一些问题，例如：

文档和项目分开维护、导致版本管理困难；
文档中的图表往往使用其他软件绘制，其他人在没有源文件的情况下难以维护；
文档中包含较多的资源文件会导致整个文档的大小变大，下载缓慢、占用资源；
使用多软件编写文档，软件付费策略各不相同合规性难以保证；
维护文档的软件的跨平台性。

解决方案及其优势

针对以上问题，在实际工作中，我找到了一种经济可行的方法。

利用 Markdown 来编写文档，实际工程项目中很多都会包含README.MD文件，我们可以使用 Markdown 将文档和项目同步进行维护；
使用对 Markdown 友好的 Mermaid 来处理所需图标，以用来解决图表维护、文档大小的问题；
使用开源/免费软件来进行文档维护。

软件选择

编辑器 VS code，其 license 授予您使用该软件的某些权利，微软保留所有其他权利。您可以使用该软件任意数量的副本，以开发并测试您的应用程序，包括在您的内部公司网络内部署；
Markdown 插件（用于预览，可选，建议安装）选择 Markdown All in One，其 license 为MIT；
图表处理使用 Mermaid，其 license 为MIT；
Mermaid 插件（用于预览，可选）选择 Markdown Preview Mermaid Support，其 license 为MIT；

以上软件、插件、项目均提供Windows、Linux、MacOS 甚至 Web 端支持。

实例

version	author	date	comment
1.0	mermaid group	2023-10-22	demo

Mermaid项目文档
- 一、简介
- 二、示例
  - 流程图
  - 时序图
  - 类图
  - 状态图
  - ER图
  - 四象限图
  - 用户体验旅程图
  - 甘特图
  - git图

Mermaid项目文档

Mermaid 被提名并获得了 JS Open Source Awards (2019) 的 “The most exciting use of technology” 奖项!!!

一、简介

Mermaid 是一个基于 Javascript 的图表绘制工具，通过解析类 Markdown 的文本语法来实现图表的创建和动态修改。Mermaid 诞生的主要目的是让文档的更新能够及时跟上开发进度。

二、示例

下面是一些可以使用 Mermaid 创建的图表示例。点击语法查看详情。

流程图

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

flowchart LR
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

时序图

sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!

sequenceDiagram
Alice->>John: Hello John, how are you?
loop Healthcheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!

类图

classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

状态图

stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]

ER图

erDiagram
    CAR ||--o{ NAMED-DRIVER : allows
    CAR {
        string registrationNumber
        string make
        string model
    }
    PERSON ||--o{ NAMED-DRIVER : is
    PERSON {
        string firstName
        string lastName
        int age
    }

erDiagram
    CAR ||--o{ NAMED-DRIVER : allows
    CAR {
        string registrationNumber
        string make
        string model
    }
    PERSON ||--o{ NAMED-DRIVER : is
    PERSON {
        string firstName
        string lastName
        int age
    }

四象限图

quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]

quadrantChart
    title Reach and engagement of campaigns
    x-axis Low Reach --> High Reach
    y-axis Low Engagement --> High Engagement
    quadrant-1 We should expand
    quadrant-2 Need to promote
    quadrant-3 Re-evaluate
    quadrant-4 May be improved
    Campaign A: [0.3, 0.6]
    Campaign B: [0.45, 0.23]
    Campaign C: [0.57, 0.69]
    Campaign D: [0.78, 0.34]
    Campaign E: [0.40, 0.34]
    Campaign F: [0.35, 0.78]

用户体验旅程图

journey
  title My working day
  section Go to work
    Make tea: 5: Me
    Go upstairs: 3: Me
    Do work: 1: Me, Cat
  section Go home
    Go downstairs: 5: Me
    Sit down: 3: Me

journey
  title My working day
  section Go to work
    Make tea: 5: Me
    Go upstairs: 3: Me
    Do work: 1: Me, Cat
  section Go home
    Go downstairs: 5: Me
    Sit down: 3: Me

甘特图

gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2014-01-12, 12d
        another task    :24d

gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2014-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2014-01-12, 12d
        another task    :24d

git图

---
title: Example Git diagram
---
gitGraph
   commit
   commit
   branch develop
   checkout develop
   commit
   commit
   checkout main
   merge develop
   commit
   commit

---
title: Example Git diagram
---
gitGraph
   commit
   commit
   branch develop
   checkout develop
   commit
   commit
   checkout main
   merge develop
   commit
   commit

参考链接

markdown
markdown 中文网
 mermaid
mermaid document
mermaid live editor