テクニカルライターのためのAI

テクニカル ライティングは長い間部分的に自動化されてきました。リファレンス ドキュメントは、Swagger UI、Redoc、Sphinx autodoc などのツールを使用して、コード コメントまたは API 仕様から定期的に生成されます。生成 AI が追加するのは散文です。つまり、製品要件ドキュメントやエンジニアリング ノートから書かれた概念的な説明、チュートリアル、例、リリース ノート、および最初の草稿です。多くのチームはコードとしてのドキュメント モデルで作業しています。ドキュメントは Git の Markdown または reStructuredText として存在し、変更はプル リクエストを通じて行われ、継続的統合により Docusaurus、MkDocs、Sphinx などの静的サイト ジェネレーターを使用してサイトが構築されます。この設定は AI に適しています。ドラフトはレビュー可能な変更として到着し、コミットごとに自動チェックが実行され、ドキュメントの更新をその原因となったコード変更に関連付けることができます。スタイルの一貫性を保つために、決定論的なツールと AI は相互に補完します。 Vale などのリンターは、スタイル ガイド (Google の開発者ドキュメント スタイル ガイドや Microsoft ライティング スタイル ガイドなど) のルールを強制し、毎回同じ結果を返します。 AI はより明確な表現を提案することに優れていますが、予測可能性は低くなります。主なリスクは、確信が不正確であることです。モデルは、エンドポイント、デフォルト値、またはもっともらしく見えるコマンドライン フラグを発明できます。また、製品が現在どのように動作するかではなく、トレーニング データでどのように動作したかを説明することもできます。生成されたすべてのコード サンプルとパラメーターは、実際のシステムに対してチェックする必要があります。よくある誤解は、AI によってテクニカル ライターが不要になるというものです。この仕事で難しいのは、何が真実かを知り、ユーザーが何を必要としているかを判断し、ユーザーが見つけられるように情報を整理することです。 Diátaxis などのフレームワークは、チュートリアル、ハウツー ガイド、リファレンス、説明を分離しており、その構造的な作業を反映しています。役割は、情報アーキテクチャ、検証、コンテンツ戦略、AI 読者向けの執筆へと移りつつあります。たとえば、2024 年の llms.txt 提案では、言語モデルをサイトの主要なドキュメントにポイントするファイルを提案しています。