技术写作
分享:
这些问题仅向参与技术写作的受访者显示。
12% 的受访者表示参与过技术写作。其中,只有 10% 担任技术文档撰写人的正式角色。
这意味着在 2023 JetBrains 开发者生态系统现状调查中,90% 的文档编写者并不称自己为技术文档撰写人,这就引发了有关团队之间协作、文档质量和一致性以及技术文档撰写人的角色的问题。

Daniele Procida
Canonical 工程总监
文档不仅在于技术写作或所写内容。它塑造了用户与产品的关系。它也会影响创作者的理解 – 每个参与产品的人都应该参与对产品的思考。
Alyssa Rock
The Good Docs Project 社区管理员
有一点仍然很清楚:开发者明白良好文档的价值(主要是因为他们知道使用文档质量差的工具有多痛苦和艰难)。他们只是有时会陷入困惑,不知道如何使文档变得更好。
Chris Chinchilla
作家和播客播主,chrischinchilla.com
在文档撰写人社区中,关于语言、工具和做法的讨论从未停歇。然而,这些数字表明,我们需要工具、培训和社区建议,让每个人都能更轻松地编写高质量文档。
内部文档
代码文档
面向客户的文档
其他
大多数受访者从事内部和代码文档工作。去年以来,从事面向客户文档工作的人员比例下降了 4 个百分点。
文档编写工具
可自定义的文本编辑器仍然是文档作者的首选工具。它们提供了一种轻量、灵活、高效的文本和代码编辑方法,因此特别适合编写文档。
不过,可自定义文本编辑器的使用率今年下降了 7 个百分点,GitHub 页面的使用率几乎相应上升了 6 个百分点。同时,协作 wiki 文档的领先范例 Confluence 则保持了其地位。
46%
39%
可定制的文本编辑器
49%
32%
Confluence 或其他 wiki 平台
28%
30%
一款办公应用程序
24%
23%
Google 文档
3% 的受访者使用专业编写辅助解决方案,其中的 42% 更喜欢定制工具。在其余选项中,唯一醒目的新工具是 Paligo,占有 5% 的份额。其他流行选项都是传统的成熟工具。
虽然参与技术写作的人中有一半以上没有考虑过使用专业工具,但仍有 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%
其他
API 文档
超过一半的受访者编写 API 参考。开发者处于领先地位,81% 表示编写 API 参考。其次是架构师 (19%)、技术文档撰写人 (18%) 和 DevOps 工程师 (17%) 等角色。其他工作角色较少参与此任务,CIO、CEO 和 CTO 等高层职位参与此活动的比例很小 (7%)。
81%
68%
开发者/程序员/软件工程师
19%
11%
架构师
18%
14%
技术文档撰写人
17%
13%
DevOps 工程师/基础架构开发者
61%
大多数 (61%) 直接从代码自动生成 API 参考,这种做法代表着高效的文档流程。在工具方面,Swagger 以 84% 的份额占据主导地位。
Swagger
ReDoc
其他
2/3
大约三分之二选择自动化的人仍然认为需要手动增强自动生成的内容。虽然自动化可以加快基础活动,但手动输入对于上下文和为 API 参考添加个人风格来说至关重要。