最近、基本設計書を書き始めた初級エンジニアです。
初めてのことばかりで、戸惑っていましたが、慣れてくると
「これさえ押さえておけばいいんじゃね？」ということが、少しづつ分かってきました。
ということで、今回は、
初級エンジニアが設計書やドキュメントを作成するときに、
「ここ押さえておけば意外といける！」という、ちょっとしたコツをまとめました。
よかったら参考にしてみてください。
文言の統一
「ください」と「下さい」とか、
「ですます」調なのか、「だである」調なのかとか、
細かい文言を統一して書くことが求めらることがあります。
正直「めんどくせー」って思いますが、
そこはぐっとこらえましょう。
ルールが決まっている現場だったらそれに従えばいいですが、
もしちゃんとしたルールが決まっていない現場だったら、自分から
「ここの文言統一した方がいいですか？」って聞いてみてください。
「お、こいつ出来るじゃん」ってなって、意外と捗るかもしれません。
特にルールはなくて、「気にしなくていいよー」って言われても、自分でルールを決めておいたら、
変に悩むこともなくなるし、後々修正しろって言われたときも楽になります。
カッコの使い方を再確認
「」鉤括弧
【】隅付き括弧
［］角括弧
（）丸括弧
などなど、
基本設計書を書くときには
【〇〇〇〇.xlsx】ファイルの［×××××］シートの「△△△△」項目参照。
といった書き方をよくします。
この、括弧の使い方も、
統一されていないところも多いと思います。
しかし、これがバラバラだったら
後々見返したときにわけわかんなくなっちゃいます。
（コーディングルールとか、命名規則といったやつも同じですね。）
これも特にルールが無いようだったら、現場のリーダーに、
「括弧の使い方、統一しましょう！」と、進言してみてください。
きっと「お、こいつ出来るな」と思われます。
エラーメッセージの出力は親切に
当たり前のことかもしれませんが、自分にとっては目からウロコだったので…
「エラーが発生しました」
というエラーメッセージだけでは不親切です。
そもそもエラーメッセージが出るということは、
ユーザーにとって「想定外のこと」が起きたということです。
そう考えると極論を言えば、エラーメッセージを全く表示させないことが理想ですが、
それは難しいですね。
本来あってはならない「想定外のこと」が起きてしまった（起こしてしまった）
ときに出るのがエラーメッセージです。
だったらそのメッセージ内容は親切に記載しましょう。
「ネットワークエラーが発生しました。通信環境を確認して再度アクセスしてください」
「ファイルのアップロードに失敗しました。アップロードファイルは.csv形式のみ選択可能です。ファイルの拡張子を確認してください。」
「システムエラーが発生しました。管理者に連絡してください」
といったように、
「エラーが発生した原因」と「その後どうすればいいか」を記載するようにしましょう。
機能と工数は比例するが、ユーザーの満足度はそうとは限らない
機能が増えれば、それを作るための工数はもちろん増えます。
しかし、機能を増やせばユーザーの満足度も上がるかと言えばそうではありません。
無駄な機能を増やしてしまったら、無駄な工数も増えるし、
ユーザーにとっても使いづらくなってしまいます。
基本設計書を書いているときに、
「他の部分でこの機能があるから、とりあえずここにも付けておこう」
といって、何も考えずに機能を増やしてしまうのはNGです。
必要な機能を必要な箇所に。
「これってなんで必要なんだろう」ということを常に意識しましょう。
行き詰まった時のリセット・切り替えの仕方
私はコーディングをしている時は、結構熱中して楽しくやれます。
けれど基本設計書などのドキュメントを作成しているときは、
ぶっちゃけつまんなくて、よくダラけます。
ダラけたり、行き詰まったりしたときは、無理に同じことを続けるのではなく、
意図的に「リセットをしよう」とした方がいいです。
私がよくやるリセット方法は「別のことをやる」か、「思い切ってサボる」ことです。
別のことをやる
・設計書の、今書いている箇所とは別の箇所を書いてみる
・エクセルのショートカットキーとか関数とかを調べてみて少しでも効率的なやり方がないか考えてみる
思い切ってサボる
・とりあえずトイレに行く
・ちょっと離れたところの自販機に飲み物を買いに行ってみる
・一服する
などなど。
サボるって言うと聞こえが悪いですが、その間もちゃんと考えています。
環境を変えたり、少し別のことをしていると、頭がスッキリします。
また急にひらめいて、その後メチャメチャ捗るようになることもあります。
レビューは早めに！
結局これが一番大事だと思います。
70％くらい出来たら、とりあえずレビューしてもらうのが良いと思います。
自分の中で「90％、いや、ほぼ100％出来た！」と思ってレビューしてもらったら、
全然ダメで、実際は60％くらいしか出来ていなかった、ということがありました。
しかも、そのうち20％くらいは無駄なこと（必要ないこと）だったりしたので、本当に時間がもったいなかった…
70％くらいでレビューしてもらった方が、その無駄な時間が少なくなります。
完成していないのにレビューしてもらうのは勇気がいりますが、ものは言いようです。
「こことここはまだ出来ていないのですが、この部分までは出来たので見てもらえませんか？」とか言えば、快くレビューしてくれる（はず）です。
そして軌道修正してもらえれば、その後の作業もまたスムーズになります。
その繰り返しです。
まとめ
いかがだったでしょうか。
ちょっとした工夫で、つまらないドキュメント作成も（ちょっとだけ）楽しくなりますし、なにより早く終わるようになります。
ドキュメント作成なんてさっさと終わらせて楽しいコーディングを始めましょう！
