技術ドキュメントの作成

共有:

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

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

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

Daniele Procida

Canonical エンジニアリング担当ディレクター

ドキュメント作成は単に技術ドキュメントを書けばよいというものではなく、何が書かれているかが重要です。ドキュメントはユーザーと製品との関係を形作るものであり、作成者がこのような関係をどのように理解するかに影響します。製品に関わる誰もがこの事を考える必要があります。

Alyssa Rock

The Good Docs Project コミュニティマネージャー

開発者が良質なドキュメントに価値を見出しているということは依然として明らかです(主にドキュメントの品質が低いツールを使用することの辛さを認識していることが理由です)。開発者は往々にしてドキュメントの品質を高める方法が分からずに困っているだけです。

Chris Chinchilla

chrischinchilla.com ライター、ポッドキャスター

ライターのコミュニティでは、言語、ツール、実践についての議論が絶えません。しかし、これらの数字を見る限り、誰もが高品質なドキュメントを作成しやすくするためのツール、トレーニング、コミュニティのアドバイスが必要であることが分かります。

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

87%

社内ドキュメント

63%

コードドキュメント

53%

顧客向けドキュメント

1%

その他

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

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

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

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

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

46%

39%

カスタマイズ可能なテキストエディター

49%

32%

Confluence または別の Wiki プラットフォーム

28%

30%

Office アプリケーション

24%

23%

Google Docs

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

42%

独自のソリューション

29%

Adobe FrameMaker

22%

Help & Manual

9%

Adobe RoboHelp

7%

ClickHelp

7%

MadCap Flare

5%

AuthorIt

5%

Paligo

10%

その他

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

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

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

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

技術ドキュメントの作成に関わったユーザーの半数以上がプロ仕様のツールの使用を検討したことがないものの、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% はおそらくツールの制限が原因で今もコピーと貼り付けを使用しており、ドキュメント作成プロセスの一貫性と速度が損なわれている可能性があります。

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

47%

はい。再利用可能なコンテンツをスニペットとして保存し、さまざまなドキュメントから参照している

32%

いいえ。使用しているツールではコンテンツの再利用がサポートされていないため、似たようなコンテンツをコピーして貼り付けている

21%

いいえ。コンテンツを再利用する必要はない

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

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

78%

各種のトピック/ドキュメント

48%

警告ブロックのような繰り返し出現するコンテンツ

29%

複雑なマークアップ要素

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

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

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

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

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

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

61%

マークアップの破損

56%

外部リンクの破損

53%

リソースの欠落

52%

内部参照の破損

47%

ドキュメント構造の破損

38%

コードサンプルの破損

6%

その他

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

54%

はい。使用しているエディターにスペルチェッカー / 文法チェックが組み込まれている

22%

いいえ。レビューに依存している

13%

外部サービスを使用している

12%

自動言語チェックを使用している

API ドキュメント

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

API リファレンスを作成していますか?

職務に応じた API リファレンスの作成

81%

68%

開発者 / プログラマー / ソフトウェアエンジニア

19%

11%

アーキテクト

18%

14%

テクニカルライター

17%

13%

DevOps エンジニア / インフラストラクチャ開発者

コードから API リファレンスを自動生成していますか?

61%

過半数を占める 61% がコードから直接 API リファレンスを自動生成しており、それが効率的なドキュメント作成プロセスであることが示されています。ツールに関しては、Swagger が 84% のシェアを占めています。

どのツールを使用していますか?

84%

Swagger

9%

ReDoc

15%

その他

自動生成された API リファレンスを手書きのコンテンツで拡張する必要がありますか?

2/3

自動化している人の約 3 分の 2 は依然として自動生成されたコンテンツを手動で拡張する必要性があると感じています。自動化は基本的な作業を高速化しますが、手動入力はコンテキストを把握して API リファレンスに人間的なタッチを加えるのに欠かせません。

言語とローカライゼーション

技術ドキュメントの最も一般的な主要言語は依然として英語です。中国語は大きく離れて 2 位でとなっており、今年は 4 パーセントポイント下落しています。日本語は昨年比で 7 パーセントポイント上昇して 3 位になっています。

ドキュメントを作成する際の主要言語は何ですか?

62%

英語

18%

中国語

13%

日本語

2%

フランス語

1%

スペイン語

1%

韓国語

1%

ドイツ語

2%

その他

ドキュメントをローカライズしていますか?

わずか 14% の回答者がドキュメントを他の言語に翻訳しており、8% が検討していると答えました。これらの数字は昨年からあまり変化していません。

技術ドキュメントの作成:

2023

最後までご覧いただきありがとうございました!

レポートはお役に立ちましたか?
ぜひこのレポートを友人や同僚と共有してください。

ご質問やご提案がございましたら、surveys@jetbrains.comまでお問合わせください。