ドキュメントを書く人でありたい。

Joel on Software
Joel on Software 青木 靖

オーム社 2005-12
売り上げランキング : 89514

おすすめ平均 star
star会社のみんなに読ませたい
starお気に入りの本です
star本当のソフト開発を本当の意味でわかってもらうのにいい本

Amazonで詳しく見る by G-Tools

ドキュメントを残す人でありたいと考え、それを模索している。Wordでテンプレートを作成してみたりとか。Webアプリの開発に携わっていると、低コストで厳しい工数を要求されるので作り出してから考えるみたいになってしまいがちだ(うちの会社では…)。工数を削減するためにドキュメント作成を省いたり、あまりに簡潔なものにしてしまうのは、逆に工数の増大を招く。

ドキュメントを書かないのか、書けないのか。最初は面倒臭がって書いてくれない!と思っていたのだが、最近になって、実は書けないんじゃないだろうか?と考えるようになった。ドキュメントは書けないけど、ソースコードは書けちゃうから書けるほうに安易に手を出して、修正依頼がきて、ブツブツと文句を言っているというような。自分はそんな人間にはなりたくないので、機能仕様書を作成してコーディングに入る前に確認を取るようにしている。これは当たり前のことのように思えるのだが、できていない人が多いんじゃないか?

機能仕様書、詳細設計書の書き方を学ぼうとネットで検索してみたりもしたが、しっくりとくるテンプレートが未だ見当たらない。機能仕様書に関しては、Joel on Softwareで書かれている方法で学習していて、なかなかいいなぁと思えるので、そちらを改良していこうと思う。問題は詳細設計書で、見ていてもしっくりくるのがない。感じたのは

  • 一見わかりやすそうで、そうでもない
  • Excelで作られているパターンが多い
  • (主観的な意見だが)読みたいと思わせてくれない作り

という点。特に最後のが重要で、せっかく作っても読まれていないということが、往々にしてある。
ということで、Wordで作ることにした。
まぁあんまり変わらんやん!って言われる可能性も高いのであるけれど、Wordでやるほうが管理上楽だし、綺麗に作る事が出来る。ドキュメントには美が必要だと思う。ドキュメントの作成にしても、最初はなかなか上達はしないので、工数もかかるだろうが、そこをちゃんと経験しないと仕様をまともに考えることがないので(頭を使わないため)、エンジニアとして実力が向上しないんじゃないだろうか?

今思うと、ドキュメント書くのが下手な人の話って、わけわからんことが多いなぁ〜と思う。何がしたいのか、何が求められているのかがブレてて、言いっぱなしで、自分でドキュメントにして形にするということがないような気がする。ドキュメントを書くプロセスを経ると、まとめるというフィルターを通した上で出来上がるので、要件もまとまるし、情報共有もスムーズになるし、他人の時間を節約することができるので費用対効果は素晴らしいものがあると思う。いいドキュメントを作成すると信頼も得られるし。

ドキュメントを作るのを面倒臭がる人は、あまりに「自分の時間」にフォーカスを当て過ぎではないだろうか?他人の時間を節約するということは、自分の時間を節約することにも繋がるので、目先の時間に捕われず、ドキュメントに時間を「投資」したほうがいいと思う。得られるのはドキュメントだけではなく、「書く力・考える力」も手に入る。そういうことが、結果的にお客さんの期待に応えることに繋がると思う。

  • どういうふうに書いたら他人に喜んでもらえるドキュメントになるだろうか?
  • 手戻りの発生しにくいプロセスにするにはどうすればいいのか?
  • このプロジェクトの目的、解決すべき本質は何か?

これを常に考えていきたい。

エンジニアのためのWord再入門講座 美しくメンテナンス性の高い開発ドキュメントの作り方
エンジニアのためのWord再入門講座 美しくメンテナンス性の高い開発ドキュメントの作り方
翔泳社 2008-05-22
売り上げランキング : 7760

おすすめ平均 star
star為になった
starすばらしいWord入門書
star数少ない、明確な視点・コンセプトのWORD本

Amazonで詳しく見る by G-Tools


タグ システム開発 | パーマリンク.

コメントを残す

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です