Docs-as-Ecosystemは、ソフトウェアエンジニアリング領域でのテクニカルライターの人が書いた書籍です。著者の方は、AsyncAPIのようなOSSのドキュメンテーションなどをやられているようです。
APIドキュメントの書き方、SDKドキュメントの書き方などは、割と詳細に書かれているので、そこでお悩みの方は読んでみるといいかもしれません。
そんな中から私が、面白いと思った2つを紹介します。
Diátaxisフレームワーク
情報アーキテクチャの整理手法の1つでコンテンツを、チュートリアル、ハウツーガイド、解説、リファレンスの4つに分けようというものです。
- チュートリアル
- ステップバイステップのガイドを提供する
- その技術や製品に不慣れな人がターゲット
- 基本的なプロセスやコンセプトを実践的に学べる
- ハウツーガイド
- アクティブなユーザが問題に遭遇した時に読むものを提供する
- 複雑なユースケースや高度なトラブルシューティングのシナリオを扱う
- 解説
- 技術の特徴や機能の概念を定義する
- コミュニティメンバがより深く理解できるようにすることを目的にする
- リファレンス
- API仕様やSDKドキュメントにアクセスする必要のあるコミュニティメンバを対象にする。
AIによってテクニカルライティングはどう変わるのか？
テクニカルライティングの分野で生成AIなどがどう影響してくるか。テクニカルライターの視点で書かれているのは、なかなか興味深いところです。
- ジュニアライターの活躍の場を広げる
- 従来はただでさえ時間を確保しにくい、シニアライターが密にコミュニケーションとってアドバイスやレビューをする必要があったが、AIがその先輩役を肩代わりしてくれる。
- 調査プロセスを加速できる
- 膨大な量のデータを素早く分析し、最も関連性の高い情報を抽出できる
- テクニカルライティングプロジェクトの新しい切り口やトピックを提案をしてもらう
- 編集とコミュニティ構築重視へのジョブチェンジ
- AIの活用で浮いた時間を、編集やコミュニティ形成に集中することに使う
- AI生成文書のファクトチェック
- AI生成文書のファクトチェックがテクニカルライターの主要な仕事になるかもしれない。少なくとも現在では、正確性、完全性、倫理遵守を慎重に管理・監視する必要がある。
まとめ
現時点では、日本では「テクニカルライター」の職種の方を見かけることはほとんどなく、ソフトウェアエンジニアがドキュメンテーションの責務を負っています。テクニカルライティングを学んでないので、いわばみんな「ジュニアライター」の状態です。Diátaxisフレームワークのようなテクニカルライティング技術をいくつか学んでおけば、生成AIにドキュメント書いてもらうにしても、より整理されたもの手に入れられるように思いました。