【コミュニティマネージャー活動ブログ】「エンジニアのためのドキュメントライティング」の紹介

こんにちは！

コミュニティマネージャーの本松です。

コミュニティマネージャーの活動の一環で、自己啓発として「エンジニアのためのドキュメントライティング」を読んだので内容について紹介させていただきます。

1.本ブログの目的

• 「エンジニアのためのドキュメントライティング」で参考になったことを共有

• ドキュメントスキルが高まる！

2.「エンジニアのためのドキュメントライティング」とは

ドキュメントの作成する目的、価値を教えてくれる本です。以下は「エンジニアのためのドキュメントライティング （単行本）」（注釈1）の抜粋です。

「ドキュメントを書いておけばよかった」

開発者であれば一度は思ったことがあるかもしれません。

ドキュメントは開発側の生産性とユーザーの利便性を高めるものです。

さらに言うと、ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。

開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。

本書は経験に長けた執筆者たちがドキュメントを作成する方法をゼロから説明するフィールドガイドです。

架空のソフトウェア開発チームのストーリーを追いながら、ソフトウェア開発ライフサイクルの各ステップにおいて、ユーザーニーズの理解、開発者に役立つドキュメントの作成、公開、測定、保守に至るまで、開発を最適化するためのドキュメント作成の技術を解説しています。

これまで学ぶ機会のなかったREADME、APIリファレンス、チュートリアル、コンセプトドキュメント、リリースノートなど、さまざまな種類のドキュメントの書き方について学ぶことができる一冊です。

ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーの方に最適の内容です。

私はドキュメント作成が得意ではありません。というか苦手です。

ドキュメントを作成する場合に何から手を付けてよいかわからないことが私がドキュメント作成を難しいと感じる点だと感じています。
そんな人にこの本はピッタリな一冊だと思います。

単純な知識を教えてくれるだけではなく、架空のソフトウェア開発チームのストーリがあり、そこに出てくる登場人物が自分のPJと重なる点を感じ、疑似的な実体験ができました。

3.学び

学んだ中で特に勉強になったこと2つを記載します。

1つ目は、1章の冒頭で登場する、知識の呪い「人間は他人が自分と同じ知識と持っていると思い込んでいる」です。

これを読んだとき、私は大きく縦に首を振り、同感しました。

仕事をしている中で目的や前提を説明できず、作業をお願いしていることやされることがあります。

本書では、解決方法として、以下を理解することが大事と記載されています。

• ユーザーのゴールを特定する

• ユーザーを理解する

• ユーザーのニーズを理解し、ドキュメントがそれをどう理解するか理解する

• わかったことをペルソナ、ストーリー、マップにまとめる

• フリクションログを使って、仮説検証する

まずは、事象を整理することが大切なんだと感じました。

ユーザーの理解すること、事象の整理することが大切なことがわかったところで、2つ目の2章ドキュメントの計画です。

ドキュメント作成の計画も正直難しいです。頭の中にある情報を適切な種類のドキュメントにどうやって落とし込めばいいんだろうといつも頭を抱えます。その中でドキュメントのコンテンツタイプごとに本書は教えてくれます。

私は「手順書」や「トラブルシューティングドキュメント」について仕事で利用することが多いので、実際に実践してみようと思いました。特にトラブルシューティングでは、いつも質問と回答形式で記載してしまい、わかりづらいものになっていると感じました。代わりに課題と解決方法に絞ったドキュメントにしようと思いました。

＜ドキュメントのコンテンツタイプ＞

• コードコメント

• README

• スタートガイド (Getting Started)

• コンセプトドキュメント

• 手順書

• チュートリアル (Tutorial)

• ハウツーガイド (How To Guide)

• リファレンスドキュメント

• API リファレンス

• 用語集

• トラブルシューティングドキュメント

• 変更に関するドキュメント (Change Log)

4.本書を通して感じたこと

今回、触れなかった後半には。ドキュメントの公開と保守という内容などがあり、普段はドキュメントの作成が作業として多いですが、不要なドキュメントを削除していくことの大切さも記載されています。

全てを取り入れることは難しいですが、まずは普段の業務で発揮しやすいところを重点的に理解することに集中しました。

まさに現場でドキュメントが最新化できていない課題ｇもあり、後回しになっていることが多いです。ただし、あくまでも方法は手段であり、目的はユーザーが求めているものを表現できることが一番です。

5.補足

本書は、翻訳者 岩瀬 義昌さんのイベント時のブログがあります。（正直こっちのほうがわかりやすいかも）

その際のアーカイブ動画が残っているので、ほんと動画を視聴することでより理解が深まりました。

▼参考元

注釈1）エンジニアのためのドキュメントライティング （単行本）
https://pub.jmam.co.jp/book/b622627.html

注釈2）「エンジニアのためのドキュメントライティング」Docs for Developers 翻訳者 岩瀬 義昌
https://pr.forkwell.com/event/docs-for-developers/

注釈3）エンジニアのためのドキュメントライティング - Forkwell Library #19
https://www.youtube.com/watch?v=766JpfhiLyI

参加申込みはこちら！

参加をご希望の方は下記のリンク先からお申込み下さい。

東京自習会の公式ラインアカウントに繋がりますので、友達追加後に【参加希望】とご連絡下さい。

▼こちらからご連絡下さい！
https://lin.ee/dZqLgaE

ご質問やご相談も公式ラインで受け付けていますので、お気軽にお問合せ下さい！

あなたのご参加お待ちしています(^▽^)/