2026.09.05 文档编写与 Git 协作培训
一、为什么办这次培训
部分社员对目前的文档编辑与协作方式存在技术上的困惑，于是约定时间做一次交流与讨论，主要围绕社内文档的撰写，以及它所依赖的相关技术。
二、培训内容
- 从零开始，对现行的编写与贡献全链路做实际操作演示；
- 介绍演示过程中出现的主要技术要点和术语；
- 阐明目前所做事务的哲学与原则。
三、详细情况与结论
1. 演示与技术要点的去向
全流程的演示视频由 Egger0 录制了主要部分。演示的操作流程与沿途讲到的技术要点，都已整理进指南，此处不再赘述——下面列出对应的页面与各自解决的问题。
演示的那条流程与相关做法，落在指南 · 手册：
| 页面 | 解决什么 |
|---|---|
| 写一页文档 | 在网页上改一页并提交，全程不装任何东西 |
| 配一台能跑本站的电脑 | 演示的那条命令行流程，每步给出命令与成功的判断标准 |
| 用 AI 帮忙写文档 | 哪些能交给 AI、哪些不能，以及怎么核实它给的东西 |
沿途讲到的技术要点与术语，落在指南 · 教程：
| 页面 | 解决什么 |
|---|---|
| 计算机网络与代理 | 浏览器能开 GitHub 而终端连不上；代理的两种模型与 Git 的代理配置层级 |
| 终端、shell 与 PATH | 命令找不到、装了新版本却不生效、配置写了不起作用 |
| 包管理器与 Node 工具链 | Homebrew、Scoop、npm、pnpm 各管什么；版本怎么锁定与对齐 |
| Git 的理念与模型 | 提交、分支、合并、变基到底在动什么；哪些概念其实属于 GitHub |
| Markdown | 常用语法，以及会让渲染失效的强调边界规则 |
| VitePress | 本站的路由与元信息、扩展语法、自有组件、三个构建命令 |
2. 为什么要建立文档项目
在过去的很长一段时间里，任何人想要了解社团发生了什么，就必须去询问参与事件的社员，或者从社长处获取会议纪要的原始纸质稿件，这造成了社员之间极大的信息差。
例如本月 25 日有一次活动，社内在 10 日召开了关于此活动的讨论会议，一名在 15 日加入或参与本事务的新社员几乎很难参与进来，想要知道 10 日发生的细节较为困难。
3. 现在的文档与会议纪要有什么问题
我想诸位可以参阅全体会议（20230312 弘毅园餐厅 全体干部及部会员）以及例会（2024-03-16）这两份纪要。
结论是显而易见的：编撰一份翔实可靠的纪要，一方面能够为后来的人员提供参考的基础，另一方面也是协会珍贵的历史沉淀。
考虑到计算机协会作为一个历史悠久的社团，这一点是值得注意的。
4. 后续
主要培训对象已经基本掌握原理，以观后续实践效果。对于其他人员，正在考虑开发一项降低一般社员编撰、上传文档门槛的功能。