技術ドキュメントの作成

これらの質問は技術ドキュメントの作成に従事している回答者のみに提示されました。

全回答者の 12% が技術ドキュメントの作成に関わっていると答えており、その中で正式なテクニカルライターの役職に就いているのは 10% のみです。

つまり、JetBrains の 2023 年開発者エコシステムの現状では、ドキュメント作成者の 90% がテクニカルライターと名乗っておらず、チーム間のコラボレーション、ドキュメントの品質と一貫性、およびテクニカルライターの役割について疑問が提起されています。

どのようなドキュメントを作成していますか？

ほとんどの回答者は内部のコードドキュメントに取り組んでいます。顧客向けのドキュメントを作成している人の割合は昨年から 4 パーセントポイント下落しています。

ドキュメントオーサリングツール

カスタマイズ可能なテキストエディターは依然としてドキュメント作成者に好まれるツールとなっています。このようなツールは軽量で柔軟性があり、効率的にテキストやコードを編集できるため、特にドキュメント作成に適しています。

ただし、今年はカスタマイズ可能なテキストエディターの使用が 7 パーセントポイント下落しており、GitHub Pages がほぼそれと同等の 6 パーセントポイント上昇しています。一方、共同型 Wiki ドキュメントの代表的な例である Confluence がその地位を維持しています。

ドキュメントの作成にはどのツールを使用していますか？

プロ仕様のヘルプオーサリングソリューションはどれを使用していますか？

プロ仕様のヘルプオーサリングソリューションを使用している 3% の回答者のうち、42% はカスタムビルドのツールを好んでいます。残りの選択肢の中では、比較的新しいツールで 5% のシェアを持つ Paligo が突出しています。使用率の高いそれ以外の選択肢は、どれも従来から存在する実績のあるツールです。

現在のソリューションに満足していますか？

ヘルプオーサリングツールを使用しているユーザーのうち、30% がより優れたツールを求めていることは注目すべきです。

技術ドキュメントの作成にプロ仕様のツールの使用を検討したことはありますか？

技術ドキュメントの作成に関わったユーザーの半数以上がプロ仕様のツールの使用を検討したことがないものの、45% というかなりの割合が前向きに検討しています。

マークアップ

Markdown が依然として最も多く選ばれています。ただし、昨年に比べると、標準的な Markdown（7 パーセントポイント下落）と Markdown フレーバー（6 パーセントポイント下落）から WYSIWYG および Office のようなアプリケーション（6 パーセントポイント上昇）へのシフトが明らかになっています。これは、ソースの管理しやすさよりも利便性や使いやすさが優先されているということなのでしょうか？

ご意見をお聞かせください

技術ドキュメントの作成にはどのマークアップ言語を使用していますか？

コンテンツの再利用とテンプレート

回答者のほぼ半数がコンテンツの再利用に構造化アプローチを使用しています。しかし、32% はおそらくツールの制限が原因で今もコピーと貼り付けを使用しており、ドキュメント作成プロセスの一貫性と速度が損なわれている可能性があります。

ドキュメント / ガイド間でコンテンツを再利用していますか？

作成プロセスを高速化するためにテンプレートを使用していますか？

テンプレートの構成対象になるものには何がありますか？

パラメーター化されたテンプレート（変数を含むテンプレートなど）を使用していますか？

回答者の 69% はテンプレートを使って作成を高速化していませんが、使用している回答者のほとんどが複数の異なるドキュメントタイプにテンプレートを使用しています。変数を使用する動的テンプレートについては、意見がほぼ分かれています。

自動チェックとドキュメントの品質

回答者のわずか 13% が技術ドキュメントの作成に自動チェックを使用しています。大多数は公開されているリンターを使う代わりにテストを社内で作成しています。これはおそらく、テストの対象が壊れたマークアップ、リンク、参照であるためだと思われます。言語とスタイルのチェックについては、組み込みのスペルチェッカーが好まれています。

技術ドキュメントの自動チェックを用意していますか？

どのようなチェックがありますか？

言語 / スタイルチェックを自動化していますか？

API ドキュメント

回答者の半数以上は API リファレンスを作成しています。最も多い API リファレンスの作成者は 81% を占める開発者です。その次にはアーキテクト（19%）、テクニカルライター（18%）、DevOps エンジニア（17%）などの職務が続いています。他の職務はこのタスクにあまり関わっておらず、CIO、CEO、CTO などの高位管理職ではわずか 7% しかこの活動に関わっていません。