Qiita
tips
新人プログラマ応援

読みやすい設計書の書き方 〜正しい日本語の使い方など〜

こんにちは。
SIerで仕事している2年目の若手SEになります。

ソースコードとコチャコチャ遊んでいる時間が殆どなので
職業柄、英語に触れ合う期間は長いです。
グローバルなこの社会で世界的公用語である英語という言語の
能力を磨くことは最早、必須ともいえるでしょう。

しかし、web界隈ではどうなのか知りませんが
SIerではそれと同じくらい、
設計者や仕様書に向き合う時間も長く、
膨大な日本語にも触れ合って来ました。

現場によっては文言まで統一された
ガチガチフォーマットもあるのでしょうが、
私が経験して来た現場は割と
フリーフォーマットの緩いところが多かったです。

そうなってくると千差万別、人の数だけ設計書があり、
そこには多種多様な日本語が見受けられて来ました。

個人的に気になることを少しだけ書きたいと思います。

日本語は文面という手段において有利

私は日本語というのは文体という世界で
非常に優秀な言語だと思っています。

それは漢字がもたらす恩恵です。
世界に色々な言語はありますが、
「文字」自体に意味を持たせることが可能な
日本語、中国語は文章によるコミュニケーションを
とる際に非常に強力なツールだとおもっています。

しかし本来の日本語のアドバンテージを
履き違えているような日本人の方が散見されます。

日本語の正しい使い方

ビジネスにおける熟語の正しい使い方を知っていますか?
何が正しくて、何が正しくないとかあるのか
と思われるかもしれません。

まず、間違った熟語の使い方はこうです。

ログインを行ったアカウントが初めてのログインである場合に、
画面Aから画面Bへの画面の遷移処理を実行する事が可能

やや大げさには書いてますが、これに近いような
冗長性を塊にしたような設計書をよく見かけます。
個人的にはベテランレガシープログラマーに
多いような気も。

こんな文章は以下のようにかけます。

初回ログインのアカウントの場合、
AからBへ画面遷移できる

スッキリしましたよね?
ポイントをピックアップして行きます。

①熟語の使い方
まず、初めての〜が「初回」の2文字で表現できてますよね?
これが正しい熟語の使い方です。

英単語では略語を使わない限り
どうしても文字数は減らせません。

②DRY原則
また、画面、画面、画面とうるさかったのが
画面遷移と書くことで前後のAとBが画面であることを
暗黙に示唆しています。

DRY原則(don't repeat yourself)は
何もメソッドなどに限りません。
同じことを何度も書かない工夫をしましょう。
引用などを使うのもベターです。

③無駄な単語
次に個人的に一番嫌いな単語、
処理、実行など。

ほんとに、その言葉必要ですか?

削除処理→削除
変換処理→変換

処理という言葉の
8割くらいは省略できるんじゃないかと思います。

「学校へ行く」ことを「登校」と2文字で
短く簡潔に表せるのが本来の熟語の利点です。

無駄に文字数を増やしていては本末転倒です。

④ひらがなの効果
また、敢えて「出来る」を平仮名で書いています。

なんでもかんでも漢字ばっか使うと
お経のようになってしまいますが、
区切りに平仮名を用いる事で
メリハリが生まれて読みやすくなります。

「従業員情報削除処理実行」
よりも
「従業員情報を削除する」
の方が読みやすいですよね。

日本語は難しい言葉を振りかざして
賢ぶる為にあるわけではありません。

「負ける」を表現するだけでも
惜敗、惨敗、完敗…
などたったの2文字で表現豊かに「負け方」を表すことができます。

短い単語の中に情報量を多く詰める事こそが
本当の美しい日本語の使い方だと思います。

見やすい図の描き方

単体テスト項目書などで使われる
マトリクス図やディシジョンテーブル。
こんな描き方していませんか?

傘の条件

晴れ
傘を持っていかない 傘を持っていく

これでは図を使っている意味がありません。

以下のように描けば見やすくなります。

傘の条件

晴れ
×

○: 傘を持っていく

少しの工夫をするだけで
あなたの設計書は途端に見やすくなります。

設計書は書くものではなく読まれる為にあるので
再度自分で読み返してみて
無駄のない美しい文章を心がけましょう。

まだまだ私の文章も精査が必要だと思いますが
ここまで読んでいただきありがとうございました。