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

体验

安装插件

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

技术文档工具『Writerside』抢鲜体验_第1张图片

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

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

官方最新插件

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

技术文档工具『Writerside』抢鲜体验_第2张图片

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

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

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

技术文档工具『Writerside』抢鲜体验_第3张图片

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

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

技术文档工具『Writerside』抢鲜体验_第4张图片

内置插件市场

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

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

技术文档工具『Writerside』抢鲜体验_第5张图片

项目体验

创建项目

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

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

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

技术文档工具『Writerside』抢鲜体验_第6张图片

创建主题

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

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

技术文档工具『Writerside』抢鲜体验_第7张图片

构建网站

技术文档工具『Writerside』抢鲜体验_第8张图片

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 发布!

你可能感兴趣的:(随笔摘录,技术文档,JetBrains,Writerside)