业务背景

接到领导消息说需要改写一份技术文档，随后给了个参考文档，简单说明了下，大致是让我把这份文档改造成一份业务通用类型的技术文档，搭一下整体架构

借鉴友商 - 需要 pdf 转 md

因为需求比较笼统，所以我就开始思考怎么写，思来想去，只能从过往接收到的友商份技术文档里借鉴一下。但是获取到的是 PDF 版本的，不好修改，作为技术人员，我们平时大都用markdwon格式，所以我就在思考怎么把 PDF 转成 md 格式

开源命令行转换工具 Pandoc

搜索的途中发现了一个开源的本地转换命令行工具 Pandoc，可以将各种文档格式转换为另一种格式，支持转换的格式很多种

尝试了下发现还要安装一些插件，及环境变量等，毕竟麻烦不想辛苦折腾，后续用在线转换工具（图个简单和快，哈哈）效果还可以，遂放弃这个方案，不过可以后续可以深度学习一下首选方案，很可能在线转换工具的背后就是使用的这个开源命令行工具

这有个部署好的的pandoc 网页版可以体验下其支持多种转换的强大功能

在线转换网站

用了些在线转换工具，发现有些不太好用，比如有些图片无法一起上传转换，还有些格式转换不太准确。

最终没办法，找到一个转换效果还行的在线转换网站，将 PDF 转成 md 格式，然后再用 vscode 编辑器进行二次编辑。

从大纲开始写

• 整理了一下后，我就按照这个大纲目录来遍写，类似企业产品的使用说明和技术接入文档(是一款语音系统)，可以简单参考下

• 途中也用到了时序图，就用的 processon，可以试试这个在线画图工具，可以画出时序图，流程图等。

• 1. 版本变更记录

• 2. 重要声明

  • 2.1. 商标声明
  • 2.2. 保密声明
  • 2.3. 版权声明

• 3. 目录

• 4. 产品介绍

• 5. 使用指南

  • 5.1. 接口风格
  • 5.2. 用户标识、密钥说明及获取方式
  • 5.3. ACCESSTOKEN 鉴权字段说明及获取方式
  • 5.4. 整体架构
  • 5.5. 参考流程
  • 5.6. 语音识别 ASR
    • 5.6.1. 语音识别 Web 接口
      • 5.6.1.1. 请求参数
      • 5.6.1.2. 返回数据结构
    • 5.6.2. 可用模型 ID 说明
    • 5.6.3. 接入自定义 ASR
      • 5.6.3.1. 主体流程
      • 5.6.3.2. 参考案例：接入阿里云 ASR
      • 5.6.3.3. 测试
  • 5.7. 声音服务/TTS
    • 5.7.1. POST 同步返回
      • 5.7.1.1. 请求参数
      • 5.7.1.2. 返回数据结构
    • 5.7.2. POST SSE 流式返回
      • 5.7.2.1. 请求参数
      • 5.7.2.2. 返回数据结构
    • 5.7.3. 接入自定义 TTS
      • 5.7.3.1. 主体流程
      • 5.7.3.2. 参考案例：接入阿里云 TTS
      • 5.7.3.3. 测试
  • 5.8. 数据模型
    • 5.8.1. AuditionDto
    • 5.8.2. TTSDto
    • 5.8.3. AsrSyncBodyDto
  • 5.9. 错误码说明
  • 5.10. 私有化部署
  • 5.11. 技术支持

• 6. 公司介绍

md 重新转回 pdf

最后把 markdown 转换成 pdf 格式 ( 防止客户收到的文档格式乱掉 )，用 vscode 编辑器的插件 Markdown PDF 进行转换, 支持导出为多种格式，包括 pdf、html、png、jpg 等。

需要 doc 格式

提交后，领导说估计需要 doc 格式，方便二次修改，所以我找到了个底层通过 pandoc 转换的 vscode 扩展插件 - vscode-pandoc，可以转换 md 到如下这些格式

获得了啥

1. 第一次去编写技术文档，发现有点像大学里的毕业论文，但是更需要保证可操作性
2. 有很多在线转换工具，但是转换效果都差强人意，最后还是 vscode 扩展插件好使
3. 这次发现了 markdown 也有很多方言语法，在不同编辑器有不同的表现（有些语法搬运到别的平台会不太一样 比如 vscode 预览和 typora 预览），增加心智负担,希望能统一起来