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

前言

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

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

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

官网地址：Writerside - a new technical writing environment from JetBrains.

技术文档

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

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

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

功能

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

体验

安装插件

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

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

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

官方最新插件

安装插件链接：Writerside - IntelliJ IDEs Plugin | Marketplace (jetbrains.com)

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

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

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

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

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

内置插件市场

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

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

项目体验

创建项目

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

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

创建文档

在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)

参考链接

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

本文由博客一文多发平台 OpenWrite 发布！