技术文档工具『Writerside』抢鲜体验

前言

2023 年 10 月 16 日，JetBrains 宣布以早期访问状态推出 Writerside，基于 IntelliJ 平台的 JetBrains IDE，开发人员可使用它编写、构建、测试和发布技术文档，可以作为 JetBrains IDE 中的插件使用，也可以作为独立工具使用

Writerside 允许开发人员和编写人员在产品文档、API 参考、开发人员指南、教程和操作方法方面进行协作；基于人工智能的拼写检查和语法纠正工具支持超过 25 种语言，包括英语、德语、西班牙语和中文

云服务器部署示例文档：About TestWriterside | TestWriterside (returntmp.fun)^[1]

官网地址：Writerside – a new technical writing environment from JetBrains.^[2]

技术文档

开发者们花费大量时间编码和构建新产品、服务和技术，但所有这些代码在上线后都需要维护，在不同阶段，特别严谨的软件开发流程，需要有大量的设计文档，详细文档。即便是缺少设计文档，也要在后期有资料来记录它的功能以及它是如何做的

对于开发者来说，写代码是很快乐的事，但写文档属实不容易，如果不写后期会引更多不必要复杂度，文档对于开发人员的生产力和客户满意度非常重要，它可以决定产品的采用或失败

根据 GitHub 相关报告数据，通过易于理解的文档，开发人员的生产力提高了近 50%

功能

文档即代码管道：使用单一创作环境，免除对多种工具的需求。借助内置 Git UI、集成式构建工具、自动化测试以及现成和可自定义的布局，专注于您的内容
**结合 Markdown 和 XML**：现在，您可以将 Markdown 与语义标记的优势相结合。选择一种格式，或使用语义特性和元素、Mermaid 图和 LaTeX 数学公式丰富 Markdown
文档质量自动化：通过编辑器中的超过 100 项即时检查以及实时预览和构建期间的测试确保文档质量和完整性
实时预览：预览显示的文档与读者将看到的完全相同。在 IDE 中预览单个页面，或在浏览器中打开整个帮助网站而不运行构建
单一来源：从较小的内容块到整个主题或目录部分，重用一切。灵活使用筛选器和变量。为复杂标记元素使用预定义模板，或者配置您自己的模板
REST API 文档生成：创建用户文档和 API 参考时无需在不同工具之间跳转。现在，您可以将 API 文档合并到帮助网站中，以相同的布局发布，并通过手动编写的内容补充自动生成的参考

体验

安装插件

官网下载链接：下载 Writerside – 文档创作工具 (jetbrains.com)^[3]

我们可以看到目前 Writerside 可以支持 Winddows、macOS、Linux 平台，同时目前处于抢先体验计划（Early Access Program，EAP）阶段，可以免费使用，以后可能会有社区免费版和旗舰付费版

我们可以下载完整的 Writerside 独立工具，如果我们已经安装 IDEA 的话，也可以使用插件方式安装，当然插件形式可能功能会不如独立工具完整，本次将会使用 IDEA 插件形式进行评测

官方最新插件

安装插件链接：Writerside – IntelliJ IDEs Plugin | Marketplace (jetbrains.com)^[4]

之后我们点击 Get 下载插件安装包

然后按照如下步骤安装插件：

打开你的集成开发环境（IDE），按下Ctrl+Alt+S打开IDE设置。
选择插件，点击⚙️，然后点击 从磁盘安装插件。
选择插件的存档文件并点击确定。
如果提示，点击确定应用更改并重新启动你的IDE。

其中可能会因为 IDEA 版本过低而出错，直接升级 IDEA 即可，操作方法如下

点击右上角的搜索图标，输入 “Check for Updates” ，然后点击搜索到的功能，然后不断 Update 即可，最后安装完插件重启即可

内置插件市场

我们也可以直接进入 IDEA ，然后进入设置界面，然后搜索插件 Writerside，然后安装插件，更加简单快捷

注：本种方法不推荐，我们可以看到下面图片中 IDEA 官方插件市场并不是 10 月的最新插件，与最新版功能有偏差

项目体验

创建项目

注：使用插件此步骤可省略

从主菜单中，选择文件 | 新 | 项目。
在新建项目向导中，选择Starter Project并单击Next。
指定新项目的名称和位置，然后单击“完成”。

创建文档

在IDEA中打开在Writerside工具窗口，打开之后有引导页，点击Add documentation按钮，然后点击 To Current Project，选择 New，然后我们添加实例名称（类似文档目录名称），之后生成即可，然后会自动生成帮助实例文档

创建主题

有了带帮助实例的文档项目之后，就可以右键目录向其中添加主题并开始编写内容，目前有5种 Markdown 主题和5种 XML 主题。

新建MD格式主题，并在其下面新建两个二级主题，左侧编写，右侧预览效果，并且可以通过拖动更改主题的层次结构。

构建网站

在Writerside工具窗口中上方有个按钮，单击”Open in Browser“或“Save as ZIP Archive”

直接本地打开网站选”Open in Browser“，文档无报错即可在浏览器中浏览文档了

如果需要发布可以选择“Save as ZIP Archive”生成压缩文件，再部署到服务器中访问

Nginx 部署

将上面的压缩包解压到服务器的目录/usr/share/nginx/writerside 中，下面是我的 nginx.conf 配置，大家可以酌情参考

server {
        listen       80;
        listen       [::]:80;
        server_name  www.returntmp.fun;
        root /usr/share/nginx;

        location ^~ / {
             root   /usr/share/nginx/blog/dist;
             index  index.html index.htm;
             try_files $uri $uri/ /index.html;
        }

        location ^~ /writerside/{
             index  index.html index.htm;
             try_files $uri $uri/ /index.html;
        }
}

部署文档示例链接：About TestWriterside | TestWriterside (returntmp.fun)^[5]

参考链接

Writerside-JetBrains的全新技术写作环境 – 知乎 (zhihu.com)^[6]
JetBrains 推出 Writerside，创建技术文档的工具 – 知乎 (zhihu.com)^[7]
新AI工具来了！开发者再也不用写文档发愁 (21cto.com)^[8]
JetBrains 首次推出“Writerside”：技术文档的新颖方法 | AppMaster^[9]

参考资料

[1]

About TestWriterside | TestWriterside (returntmp.fun): http://www.returntmp.fun/writerside/starter-topic.html

[2]

Writerside – a new technical writing environment from JetBrains.: https://www.jetbrains.com/writerside/

[3]

下载 Writerside – 文档创作工具 (jetbrains.com): https://www.jetbrains.com/zh-cn/writerside/download/#section=windows

[4]

Writerside – IntelliJ IDEs Plugin | Marketplace (jetbrains.com): https://plugins.jetbrains.com/plugin/20158-writerside

[5]

About TestWriterside | TestWriterside (returntmp.fun): http://www.returntmp.fun/writerside/starter-topic.html

[6]

Writerside-JetBrains的全新技术写作环境 – 知乎 (zhihu.com): https://zhuanlan.zhihu.com/p/662270037

[7]

JetBrains 推出 Writerside，创建技术文档的工具 – 知乎 (zhihu.com): https://zhuanlan.zhihu.com/p/661832996

[8]

新AI工具来了！开发者再也不用写文档发愁 (21cto.com): https://www.21cto.com/article/2475624056949539

[9]

JetBrains 首次推出“Writerside”：技术文档的新颖方法 | AppMaster: https://appmaster.io/zh/news/jetbrains-shou-ci-tui-chu-writerside-ji-zhu-wen-dang-de-xin-ying-fang-fa