技术写作

分享:

这些问题仅向参与技术写作的受访者显示。

12% 的受访者表示参与过技术写作。其中,只有 10% 担任技术文档撰写人的正式角色。

这意味着在 2023 JetBrains 开发者生态系统现状调查中,90% 的文档编写者并不称自己为技术文档撰写人,这就引发了有关团队之间协作、文档质量和一致性以及技术文档撰写人的角色的问题。

Daniele Procida

Canonical 工程总监

文档不仅在于技术写作或所写内容。它塑造了用户与产品的关系。它也会影响创作者的理解 – 每个参与产品的人都应该参与对产品的思考。

Alyssa Rock

The Good Docs Project 社区管理员

有一点仍然很清楚:开发者明白良好文档的价值(主要是因为他们知道使用文档质量差的工具有多痛苦和艰难)。他们只是有时会陷入困惑,不知道如何使文档变得更好。

Chris Chinchilla

作家和播客播主,chrischinchilla.com

在文档撰写人社区中,关于语言、工具和做法的讨论从未停歇。然而,这些数字表明,我们需要工具、培训和社区建议,让每个人都能更轻松地编写高质量文档。

您编写什么类型的文档?

87%

内部文档

63%

代码文档

53%

面向客户的文档

1%

其他

大多数受访者从事内部和代码文档工作。去年以来,从事面向客户文档工作的人员比例下降了 4 个百分点。

文档编写工具

可自定义的文本编辑器仍然是文档作者的首选工具。它们提供了一种轻量、灵活、高效的文本和代码编辑方法,因此特别适合编写文档。

不过,可自定义文本编辑器的使用率今年下降了 7 个百分点,GitHub 页面的使用率几乎相应上升了 6 个百分点。同时,协作 wiki 文档的领先范例 Confluence 则保持了其地位。

您使用什么工具编写文档?

46%

39%

可定制的文本编辑器

49%

32%

Confluence 或其他 wiki 平台

28%

30%

一款办公应用程序

24%

23%

Google 文档

您使用哪种专业编写辅助解决方案?

42%

定制解决方案

29%

Adobe FrameMaker

22%

Help & Manual

9%

Adobe RoboHelp

7%

ClickHelp

7%

MadCap Flare

5%

AuthorIt

5%

Paligo

10%

其他

3% 的受访者使用专业编写辅助解决方案,其中的 42% 更喜欢定制工具。在其余选项中,唯一醒目的新工具是 Paligo,占有 5% 的份额。其他流行选项都是传统的成熟工具。

您是否对当前的解决方案满意?

在使用编写辅助工具的用户中,有 30% 正在寻求更好的替代品。

您是否考虑过使用专业工具进行技术写作?

虽然参与技术写作的人中有一半以上没有考虑过使用专业工具,但仍有 45% 的人对此持开放态度。

标记

Markdown 仍然是主要选择。不过,与去年相比,从标准 Markdown(下降 7 个百分点)和 Markdown 变种(下降 4 个百分点)到所见即所得和 Office 式应用程序(上升 6 个百分点)发生了明显的转变。这是否表明对源的控制让位于便利性或用户友好性?

告诉我们您的想法

您使用哪种(哪些)标记语言编写技术文档?

77%

70%

Markdown

18%

24%

不确定/我使用所见即所得编辑器或类似于 Office 的应用程序

13%

9%

定制 Markdown 变体

5%

6%

XML/DITA/DocBook 等

5%

5%

AsciiDoc

4%

4%

reStructuredText

4%

3%

其他

内容重用和模板

约有一半受访者使用结构化方式重用内容。然而,可能是由于其工具的局限,32% 仍然选择复制粘贴,进而可能导致不一致并减慢文档流程。

您是否在不同的文档/指南之间重用内容?

47%

是,我将可重用的内容存储在代码段中,并在不同的文档中引用它们

32%

否,我的工具不支持重用内容,因此我复制粘贴类似内容

21%

否,我不需要重用内容

您是否使用模板加快编写过程?

您为什么类型的内容配置模板?

78%

不同类型的主题/文档

48%

重复内容,如警告块

29%

复杂的标记元素

您是否创建参数化模板(例如包含变量的模板)?

69% 的受访者不使用模板加快编写速度,但在使用模板的受访者中,大多数将其用于不同的文档类型。对于带有变量的动态模板,意见几乎均匀分布。

自动化检查和文档质量

只有 13% 的受访者在技术文档中使用自动化检查。绝大多数人在内部编写测试,而不是使用公共 linter,大概是因为测试针对的是损坏的标记、链接和引用。对于语言和样式检查,内置拼写检查器更受青睐。

您是否有技术文档的自动检查?

您有什么类型的检查?

61%

损坏的标记

56%

损坏的外部链接

53%

缺少资源

52%

损坏的内部引用

47%

损坏的文档结构

38%

损坏的代码示例

6%

其他

您是否自动执行语言/样式检查?

54%

是,我的编辑器有一个内置的拼写检查器/语法检查器

22%

否,我们依靠审查

13%

我使用外部服务

12%

我们有自动化语言检查

API 文档

超过一半的受访者编写 API 参考。开发者处于领先地位,81% 表示编写 API 参考。其次是架构师 (19%)、技术文档撰写人 (18%) 和 DevOps 工程师 (17%) 等角色。其他工作角色较少参与此任务,CIO、CEO 和 CTO 等高层职位参与此活动的比例很小 (7%)。

您是否编写 API 引用?

按工作角色的 API 参考编写

81%

68%

开发者/程序员/软件工程师

19%

11%

架构师

18%

14%

技术文档撰写人

17%

13%

DevOps 工程师/基础架构开发者

您是否会从代码中自动生成 API 参考?

61%

大多数 (61%) 直接从代码自动生成 API 参考,这种做法代表着高效的文档流程。在工具方面,Swagger 以 84% 的份额占据主导地位。

您使用什么工具?

84%

Swagger

9%

ReDoc

15%

其他

您是否需要使用手动编写的内容扩展自动生成的 API 参考?

2/3

大约三分之二选择自动化的人仍然认为需要手动增强自动生成的内容。虽然自动化可以加快基础活动,但手动输入对于上下文和为 API 参考添加个人风格来说至关重要。

语言和本地化

英语仍然是技术文档中最流行的主要语言。汉语以较大差距占据次席,今年下降了 4 个百分点。日语排名第三,比去年上升了 7 个百分点。

您编写文档使用的主要语言是什么?

62%

英语

18%

中文

13%

日语

2%

法语

1%

西班牙语

1%

韩语

1%

德语

2%

其他

您是否本地化文档?

只有 14% 的受访者将其文档翻译成其他语言,8% 的受访者正在考虑这样做。这些数字相较去年没有明显变化。

技术写作:

2023

感谢您的参与!

我们真诚地希望您能发现我们的报告有用。与您的朋友和同事分享这份报告。

如果您有任何疑问或建议,请发送电子邮件至 surveys@jetbrains.com