技術ドキュメントの作成

共有:

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

全回答者の 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 がその地位を維持しています。

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

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

プロ仕様のヘルプオーサリングソリューションを使用している 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% しかこの活動に関わっていません。

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

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

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

61%

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

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

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

2/3

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

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

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

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

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

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

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

2023

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

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

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