engineers_blog新年あけましておめでとうございます。MFクラウドシリーズの最新プロダクト「MFクラウド経費」の開発を担当しています、Railsエンジニアの黒田と申します。今回は『エンジニア3大がっかり』のひとつ、ドキュメントの陳腐化について書きたいと思います。ドキュメントの陳腐化対応エンジニアの皆さんなら、陳腐化するドキュメントにがっかりしたご経験があるかと思います。新機能の追加に際して、これがあるから気乗りがしない・・・なんてことも。ドキュメントの陳腐化に我々はどう立ち向かえば良いのでしょうか?個人的に思いついたものを上げてみます。無駄なドキュメントを書かない元も子もない話のようですが、ドキュメントを一度作成してしまったがために、その後メンテナンスせざるを得ないという事に陥りがちです。ドキュメントをそもそも書かないで済ますということも大事なのではと思っています。メンテコストに見合うのかなどを再確認すると良いですね。意外と書かないで済んでしまうドキュメントもあるように思います。何も書かないと、暗黙知となり誰も理解できないシロモノが作られてしまうので、そこは何かしら情報が残るようにする必要はあります。マネーフォワードのようなエンジニアドリブンで自社サービスの開発に取り組んでいる組織であれば、実装上の大抵の事はソースコードのコメントで済ましてしまって良いと思います。ソースコードのコメントであれば、仕様変更などでコード修正が発生した際に、コメントも同時に修正できて、レビューにもかけれるので楽ちんです。Excelやスプレッドシートはリスト形式のドキュメント以外では使わない時折、ミリ単位のセル調整などを駆使した芸術的なExcelドキュメントを目にするのですが、恥ずかしながらExcelのセル調整が不得手な私のような人間に取っては、こういったドキュメントをメンテナンスするのは大変な労力を要します。ドキュメントは陳腐化するし、メンテナンスする人も変わっていくので、こういったメンテナンスに労力のかかるドキュメントは作らないようにした方が良いと思います。マネーフォワードでは、ドキュメントの共有には「esa」などを活用しています。マークダウンでドキュメントを書くので、誰でも簡単にドキュメントの編集ができます。マネーフォワードではAPIを社外に公開しており、社外の方と開発に関してのやり取りも増えてきているのですが、社外の方とのドキュメントのやり取りも出来るだけExcelやスプレッドシートを使わないようにしています。自動で出力されるテーブル定義書になりますし、autodocというgemを使うとテストコードを用意するだけでAPI仕様書の作成を自動化できます。autodocは大変重宝しており、「MFクラウド経費」のスマホエンジニアとサーバーサイドのエンジニア(私)の意思疎通も快適にできます。自動出力される情報では足りないという懸念もあるかもしれませんが、同じチームのエンジニア間のやり取りとしては十分であったりします。autodocはプログラムもドキュメントの保守にも良いのでオススメです。最後にマネーフォワードでは、ドキュメントの陳腐化に涙したご経験をお持ちで、その課題に立ち向かっていくエンジニアを絶賛募集しています。ご応募お待ちしています。