技術ドキュメントの作成
共有:
これらの質問は技術ドキュメントの作成に従事している回答者のみに提示されました。
全回答者の 12% が技術ドキュメントの作成に関わっていると答えており、その中で正式なテクニカルライターの役職に就いているのは 10% のみです。
つまり、JetBrains の 2023 年開発者エコシステムの現状では、ドキュメント作成者の 90% がテクニカルライターと名乗っておらず、チーム間のコラボレーション、ドキュメントの品質と一貫性、およびテクニカルライターの役割について疑問が提起されています。

Daniele Procida
Canonical エンジニアリング担当ディレクター
ドキュメント作成は単に技術ドキュメントを書けばよいというものではなく、何が書かれているかが重要です。ドキュメントはユーザーと製品との関係を形作るものであり、作成者がこのような関係をどのように理解するかに影響します。製品に関わる誰もがこの事を考える必要があります。
Alyssa Rock
The Good Docs Project コミュニティマネージャー
開発者が良質なドキュメントに価値を見出しているということは依然として明らかです(主にドキュメントの品質が低いツールを使用することの辛さを認識していることが理由です)。開発者は往々にしてドキュメントの品質を高める方法が分からずに困っているだけです。
Chris Chinchilla
chrischinchilla.com ライター、ポッドキャスター
ライターのコミュニティでは、言語、ツール、実践についての議論が絶えません。しかし、これらの数字を見る限り、誰もが高品質なドキュメントを作成しやすくするためのツール、トレーニング、コミュニティのアドバイスが必要であることが分かります。
社内ドキュメント
コードドキュメント
顧客向けドキュメント
その他
ほとんどの回答者は内部のコードドキュメントに取り組んでいます。顧客向けのドキュメントを作成している人の割合は昨年から 4 パーセントポイント下落しています。
ドキュメントオーサリングツール
カスタマイズ可能なテキストエディターは依然としてドキュメント作成者に好まれるツールとなっています。このようなツールは軽量で柔軟性があり、効率的にテキストやコードを編集できるため、特にドキュメント作成に適しています。
ただし、今年はカスタマイズ可能なテキストエディターの使用が 7 パーセントポイント下落しており、GitHub Pages がほぼそれと同等の 6 パーセントポイント上昇しています。一方、共同型 Wiki ドキュメントの代表的な例である Confluence がその地位を維持しています。
46%
39%
カスタマイズ可能なテキストエディター
49%
32%
Confluence または別の Wiki プラットフォーム
28%
30%
Office アプリケーション
24%
23%
Google Docs
プロ仕様のヘルプオーサリングソリューションを使用している 3% の回答者のうち、42% はカスタムビルドのツールを好んでいます。残りの選択肢の中では、比較的新しいツールで 5% のシェアを持つ Paligo が突出しています。使用率の高いそれ以外の選択肢は、どれも従来から存在する実績のあるツールです。
技術ドキュメントの作成に関わったユーザーの半数以上がプロ仕様のツールの使用を検討したことがないものの、45% というかなりの割合が前向きに検討しています。
マークアップ
Markdown が依然として最も多く選ばれています。ただし、昨年に比べると、標準的な Markdown(7 パーセントポイント下落)と Markdown フレーバー(6 パーセントポイント下落)から WYSIWYG および Office のようなアプリケーション(6 パーセントポイント上昇)へのシフトが明らかになっています。これは、ソースの管理しやすさよりも利便性や使いやすさが優先されているということなのでしょうか?
77%
70%
Markdown
18%
24%
分からない / WYSIWYG エディターまたは Office 系のアプリケーション
13%
9%
カスタムの Markdown フレーバー
5%
6%
XML / DITA / DocBook など
5%
5%
AsciiDoc
4%
4%
reStructuredText
4%
3%
その他
コンテンツの再利用とテンプレート
回答者のほぼ半数がコンテンツの再利用に構造化アプローチを使用しています。しかし、32% はおそらくツールの制限が原因で今もコピーと貼り付けを使用しており、ドキュメント作成プロセスの一貫性と速度が損なわれている可能性があります。
はい。再利用可能なコンテンツをスニペットとして保存し、さまざまなドキュメントから参照している
いいえ。使用しているツールではコンテンツの再利用がサポートされていないため、似たようなコンテンツをコピーして貼り付けている
いいえ。コンテンツを再利用する必要はない
各種のトピック/ドキュメント
警告ブロックのような繰り返し出現するコンテンツ
複雑なマークアップ要素
API ドキュメント
回答者の半数以上は API リファレンスを作成しています。最も多い API リファレンスの作成者は 81% を占める開発者です。その次にはアーキテクト(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
自動化している人の約 3 分の 2 は依然として自動生成されたコンテンツを手動で拡張する必要性があると感じています。自動化は基本的な作業を高速化しますが、手動入力はコンテキストを把握して API リファレンスに人間的なタッチを加えるのに欠かせません。
最後までご覧いただきありがとうございました!
レポートはお役に立ちましたか?
ぜひこのレポートを友人や同僚と共有してください。
ご質問やご提案がございましたら、surveys@jetbrains.comまでお問合わせください。