エンジニア３大がっかりのひとつ　ドキュメントの陳腐化への対応

新年あけましておめでとうございます。

MFクラウドシリーズの最新プロダクト「MFクラウド経費」の開発を担当しています、Railsエンジニアの黒田と申します。

今回は『エンジニア３大がっかり』のひとつ、ドキュメントの陳腐化について書きたいと思います。

ドキュメントの陳腐化対応

エンジニアの皆さんなら、陳腐化するドキュメントにがっかりしたご経験があるかと思います。
新機能の追加に際して、これがあるから気乗りがしない・・・なんてことも。

ドキュメントの陳腐化に我々はどう立ち向かえば良いのでしょうか？

個人的に思いついたものを上げてみます。
　■ 1. 無駄なドキュメントを書かない
　■ 2. エクセルやスプレッドシートはリスト形式のドキュメント以外では使わない
　■ 3. ドキュメント出力を自動化する

元も子もない話のようですが、ドキュメントを一度作成してしまったがために、その後メンテナンスせざるを得ないという事に陥りがちです。

なら、ドキュメントをそもそも書かないで済ますということも大事なのではと思っています。

ドキュメント作成にあたり、
　■ このドキュメントが本当に必要なのか
　■ 作らない他の選択肢は無いのか
　■ メンテコストに見合うのか
などを再確認すると良いですね。

意外と書かないで済んでしまうドキュメントもあるように思います。
もちろん何も書かないと、暗黙知となり誰も理解できないシロモノが作られてしまうので、そこは何かしら情報が残るようにする必要はあります。

マネーフォワードのようなエンジニアドリブンで自社サービスの開発に取り組んでいる組織であれば、実装上の大抵の事はソースコードのコメントで済ましてしまって良いと思います。

ソースコードのコメントであれば、仕様変更などでコード修正が発生した際に、コメントも同時に修正できて、レビューにもかけれるので楽ちんです。

時折、ミリ単位のセル調整などを駆使した芸術的なExcelドキュメントを目にするのですが、恥ずかしながらExcelのセル調整が不得手な私のような人間に取っては、こういったドキュメントをメンテナンスするのは大変な労力を要します。

ドキュメントは陳腐化するし、メンテナンスする人も変わっていくので、こういったメンテナンスに労力のかかるドキュメントは作らないようにした方が良いと思います。

マネーフォワードでは、ドキュメントの共有には「esa」などを活用しています。
マークダウンでドキュメントを書くので、誰でも簡単にドキュメントの編集ができます。

また、マネーフォワードではAPIを社外に公開しており、社外の方と開発に関してのやり取りも増えてきているのですが、社外の方とのドキュメントのやり取りも出来るだけExcelやスプレッドシートを使わないようにしています。
・マネーフォワード api-doc
・MFクラウド請求書 api-doc

そんな便利な話があれば苦労しないよという話なのですが、Railsの場合はdb/schema.rb が自動で出力されるテーブル定義書になりますし、autodocというgemを使うとテストコードを用意するだけでAPI仕様書の作成を自動化できます。

autodocは大変重宝しており、「MFクラウド経費」のスマホエンジニアとサーバーサイドのエンジニア（私）の意思疎通も快適にできます。

自動出力される情報では足りないという懸念もあるかもしれませんが、同じチームのエンジニア間のやり取りとしては十分であったりします。autodocはプログラムもドキュメントの保守にも良いのでオススメです。

マネーフォワードでは、ドキュメントの陳腐化に涙したご経験をお持ちで、その課題に立ち向かっていくエンジニアを絶賛募集しています。
ご応募お待ちしています。

株式会社マネーフォワードでは一緒に働く仲間を募集しています

エンジニア３大がっかりのひとつ　ドキュメントの陳腐化への対応

小川昌之

株式会社マネーフォワード / ビジネスカンパニー SMB事業推進本部新規事業開発部