Developer Ecosystem

Tech Writing

Share:

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.

Daniele Procida

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.

Alyssa Rock

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.

Chris Chinchilla

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.

What type of documentation do you write?

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.

Documentation authoring tools

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.

What tools do you use to author documentation?

Which professional help authoring solution do you use?

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.

Are you happy with your current solution?

A notable 30% of those using a help authoring tool are seeking something better.

Have you considered using a professional tool for technical writing?

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.

Markup

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?

Tell us what you think

Which markup language do you use to write technical documentation?

Content reuse and templates

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.

Do you reuse content between different documents / guides?

Do you use templates to speed up the writing process?

What kind of things do you configure templates for?

Do you create parameterized templates (e.g. templates containing variables)?

69% of respondents don’t use templates to speed up writing, but of those who do, most use them for different document types. As for dynamic templates with variables, opinions are nearly split.

Automated checks and documentation quality

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.

Do you have automated checks for technical documentation?

What types of checks do you have?

Do you automate language / style checks?

API documentation

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.

Do you write API references?

API references writing depending on job role

Do you automatically generate the API reference from the code?

61%

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.

What tools do you use?

Do you need to extend automatically generated API references with manually written content?

2/3

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.

Languages and localization

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.

What is the primary language that you write documentation in?

Do you localize documentation?

Only 14% of respondents translate their documentation into other languages, with 8% considering it. These figures haven’t changed significantly since last year.

Writerside

A new documentation authoring and publishing platform

NEW

Previous

Team Tools

Next

Testing

Tech Writing:

2023

2022
2021

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.

Sign Up

Learn more

Raw data Soon

We are preparing the raw data. You can leave your email to get notified when it is available for download.

By submitting this form I agree to the JetBrains Privacy Policy

If you have any questions or suggestions, please contact us at surveys@jetbrains.com.