These questions were only shown to the respondents who are involved in technical writing.
12% of all respondents said they were involved in technical writing. Among them, only 10% hold an official job role as technical writers.
This means that in the JetBrains State of Developer Ecosystem 2023, 90% of those who write documentation don’t call themselves technical writers, which raises questions about collaboration between teams, documentation quality and consistency, and the role of technical writers.
Director of Engineering, Canonical
Documentation isn’t just about technical writing, or what gets written. It shapes a user’s relationship with a product. It affects how its creators understand it, too – everyone involved in a product should be engaged in thinking about it.
Community Manager, The Good Docs Project
One thing remains clear: the devs see the value of good documentation (mostly because they know how painful and difficult it can be to use a tool that has poor documentation). They just sometimes feel at a loss to know how to make their documentation good.
Writer and Podcaster, chrischinchilla.com
Among our writers’ community, we have endless discussions about language, tools, and practices. However, these numbers show that we need tooling, training, and community advice that makes it easier for everyone and anyone to write quality documentation.
Most respondents work on internal and code documentation. Since last year, the proportion of those working on customer-facing documentation has decreased by four percentage points.
Customizable text editors are still the tool of choice for documentation authors. They provide a lightweight, flexible, and efficient means of editing text and code, making them particularly suited for writing documentation.
However, this year saw a decline of seven percentage points in the use of customizable text editors, coupled with a nearly equivalent rise of six percentage points in GitHub pages. Meanwhile, Confluence, a leading example of collaborative wiki documentation, maintains its position.
Of the 3% of respondents who use a professional help authoring solution, 42% prefer custom-built tools. Among the remaining options, the only newer tool that stands out is Paligo with a 5% share. The other popular options are all traditional, established tools.
While over half of those involved in technical writing haven’t thought of using a professional tool, a significant 45% are open to the idea.
Markdown remains the predominant choice. Compared to last year however, there is a clear shift from standard Markdown (down by 7 percentage points) and Markdown flavors (down by 4 percentage points) to WYSIWYG and Office-like applications (up by 6 percentage points). Does this mean that control over sources is taking a back seat to convenience or user-friendliness?
Almost half of the respondents use a structured approach to reusing content. Yet, 32% still copy and paste, possibly because of their tools’ limitations, which can cause inconsistencies and slow down the documentation process.
Only 13% of respondents use automated checks in technical documentation. The vast majority write their tests in-house rather than using public linters, presumably because the tests target broken markup, links, and references. For language and style checks, built-in spellcheckers are favored.
Over half of the respondents write API references. Developers take the lead, with 81% saying they write API references. This is followed by roles like Architects (19%), Technical Writers (18%), and DevOps Engineers (17%). Other job roles are less involved in this task, and higher-up positions like CIOs, CEOs, and CTOs have a small percentage (7%) involved in this activity.
The majority, 61%, automatically generate API references directly from the code, a practice indicative of efficient documentation processes. As for tools, Swagger dominates the landscape with an 84% share.
About two-thirds of those who automate still find the need to manually enhance their automatically generated content. While automation speeds up the basics, manual input is key for context and adding a personal touch to API references.
English is still the most popular primary language for tech documentation. Chinese comes a distant second, this year losing four percentage points. Japanese occupies the third place, having gained seven percentage points since last year.
Only 14% of respondents translate their documentation into other languages, with 8% considering it. These figures haven’t changed significantly since last year.
Thank you for your time!
We hope you found our report useful. Share this report with your friends and colleagues.
Join JetBrains Tech Insights Lab
Take part in surveys and UX studies to make JetBrains products easier to use yet even more powerful. For participating in our research, you’ll also get the chance to earn rewards.
Raw data Soon
We are preparing the raw data. You can leave your email to get notified when it is available for download.
If you have any questions or suggestions, please contact us at firstname.lastname@example.org.