ドキュメント作成のTips～良いドキュメントとは～

皆さんこんにちは！Marvelの広報渡邊です🌸
先日投稿したエンジニアインタビュー【vol.12】の記事はもうご覧いただきましたか？？😳

こちらの記事でご紹介したエンジニアの阿部さんは、ドキュメント作成が非常に得意なエンジニアさんで、実際に現在参画されているプロジェクトで、阿部さんが作成した詳細設計の資料が、

🎉🎉現場全体の標準フォーマットとして採用されたそうです🥳🙌

今回はそんな阿部さんにインタビュー形式でドキュメント作成のTipsを聞いてみました💡
現在、また今後設計資料作成業務を担当する方も多いと思いますので、ぜひご覧ください👀

インタビュー

(今回はキャリア管理部の海野さんも同席し3人で和やかな雰囲気でのインタビュー🎤)

渡邊：阿部さん、お疲れ様です☕今月で2回もインタビューにご協力いただきありがとうございます🙇🏻‍♀️🙌
もうさっそくインタビューしていきますね！
ズバリ、阿部さんが思う「良いドキュメント」とはどんなドキュメントですか？

阿部：どの立場の方から見ても、内容がわかるドキュメントだと思います！

渡邊：なるほど．．．ではそのようなドキュメントを作成するにあたり、阿部さんご自身が普段ドキュメント作成において意識している点はどこですか🤔🤔

阿部：設計や製造、テストなど担当分野が違う方とか、日本語が第一言語ではない方にも内容が一意に伝わるように、難しい用語を使わないようにするとか、言葉の言い回しに気を付けています👀
あとは図があった方が確実に伝わるので１枚以上載せるようにしています。今回はエクセルベースで出力データのマッピング図や、フロー図であったり、シーケンス図も作りました。いろんな図を使い分けて作成します💡

渡邊：今回現場全体の標準フォーマットに採用されたことに関して、阿部さんご自身ではどういった点が評価されたと感じていますか？🤔
また、現場でいただいたFB（評価点やフォーマット化の理由）などありますか？😳

阿部：僕が作ったドキュメントよりもっと細かい方もいらっしゃいましたが、図を使ったものだったことと、求められていた粒度と一番近かった点が評価されたと思います🙌
フォーマット化の理由は、先に言った粒度が決め手のようでした。

海野：ドキュメント作成の能力は勿論なのですが、阿部さんの場合はコミュニケーションスキルもあるからこそ書けるドキュメントなのかな、と思うんですよね😳
相手（クライアントやメンバー）から求められているものは何かをキャッチする力に優れているという印象があります😌💭

阿部：アンテナは広いと思います📡作業をしながらも周囲での会話を聞いて、開発現場全体の状況を把握したりしています💡

海野：そうなんですね！そういうところも、阿部さんのドキュメント作成に活かされているのではないかと思います✨✨これって元々のセンスなんですかね？

阿部：元々周りの雰囲気などに気を配るタイプではありました。あと、前職が社内システム部という部署で開発業務だけでなくトラブル対応などシステムの開発・運用の全般サイクルなどに対応する部署だったので、（関わる工程以外の）周りへのアンテナを常に張っていました👀💡📡

海野：前職の経験も活かされているんですね！開発だけでなく、運用後も想定して設計できるところは、その経験がバックグラウンドとして強みになっていると思います🔥

渡邊：ずっと気になっていたのですが、どうやってドキュメント作成のスキルを身につけたんですか？（前職での経験、自己学習など）

阿部：前職の部長がうまくドキュメントをまとめる方だったので自然と参考にするようになっていました🧐

渡邊：吸収力が素晴らしいです！
部長さんのドキュメントのどんなところに上手いなと感じたんですか？👀

阿部：
・文が一文一文短いところ
・見出しがそれぞれの項目についている
・図が一つ一つ貼ってある
・全部のドキュメントを通して、「この人が作ったんだな」と分かるような
統一感がある
というところがいいなと感じて、どんどん真似するようになりました。

海野：ご自身でググったり、ドキュメントに関して書籍を読んで勉強したりはしたんですか？

阿部：書籍は特にないですね！その都度調べる感じでやってます！🔎💻

海野：そうなんですね！阿部さんの例だと前職の上司の方であったり、先輩や有識者のヒントを真似ながら/学びながらしっかり身に付けていくってなかなか全員にできることじゃないので、やはり普段の阿部さんの仕事に対する姿勢が作成するドキュメントにも現れているのではないかなと思います。

(今回もインタビューに参加してくれたミントちゃん🐈)

渡邊：阿部さんからエンジニアの皆さんへ、ドキュメント作成に関するアドバイスが他にあればお願いします！

阿部：自分のフォーマットをいくつか持っておくといいと思います。フリーフォーマットが許されるのであれば、その引き出しの中から使用することで作成したドキュメントに統一感が出るのでおすすめです🙌🙌

渡邊：阿部さんはいくつかフォーマットを持ってるんですか？？

阿部：エクセル１パターン、文字ベース１パターンというように、作る媒体によってこういう感じで作ろっかな～というのはあります💡

所属チームにとどまらず、開発の現場全体の模範となるようなドキュメントをで作成している阿部さん🐈
初めはドキュメントのTipsとしてインタビューをしていましたが、阿部さんのそのスキルの背景には、阿部さんのアンテナの広さや、開発側以外の立場への配慮だったりと、本来のお人柄や仕事に対する丁寧な姿勢があるのだとわかりました🐈‍⬛🫧

インタビュー後、阿部さんと海野さんと少し世間話のようなものもしたのですが、Marvelに今後ペットコミュニティみたいな、カジュアルにペットに関するチャットをしあえる場所があったら良さそう！という話になりました✨
私はペットを飼っていませんが、そんなコミュニティができたら見る専門として絶対に参加します！🐱🐶🐦🐹🐰