Skip to content
Neos21 edited this page Nov 18, 2019 · 1 revision

全てのドキュメントに書くべきヘッダ

  • タイトル
    • 何のためのドキュメントであるかを一言で伝える。名前重要
    • 何が書いてあり、何が書いてなさそうかを伝える
  • 成果物 ID
    • 「成果物一覧」と比較して、納品時に過不足がないか確認できるようにするため
    • 納品しないドキュメントの場合も、「どのドキュメントについて話しているか」をチーム内で明らかにするため、何らか一意になる ID を設けておくと良い
  • 初版作成日
    • いつ頃作られたドキュメントか分かる → そのドキュメントが作られた起因を後で追いやすい (作成日の少し前に作成 or 更新されたドキュメントを見つけやすくなると、経緯も追いやすい)
  • 初版作成者
    • 誰が作ったドキュメントか分かる → ドキュメントの内容に関して質問したいことがある時、相手が分かる
  • 最終更新日
    • 最後に更新された日付が分かる → きちんとメンテナンスされているドキュメントか、放置されているドキュメントかの区別が付く
    • 放置されているドキュメントは「誤りになった」情報を含んでいる可能性が高く、信頼性に欠ける。そのつもりで読みやすい
  • 最終更新者
    • 最後に更新した人が分かる → 最後の更新内容に関する質問がある時、相手が分かる

全てのドキュメントで個別に定めておくべきルール

  • 記載範囲
    • そのドキュメントに何を記載して、何を記載しないか、を明記する
    • (一見関連しそうだが) そのドキュメントに記載しないことにした事柄については、代わりにどこで説明しているか、関連ドキュメント名やリンクを記しておく
      • ex. この画面仕様書は、「○○」画面の仕様を記す。「○○」画面と対になる「○○」帳票の仕様については記載しない。別途「○○帳票仕様書」を参照のこと
  • 更新の要領
    • そのドキュメントをどういうタイミングで、どのように更新して良いか。更新時の禁止事項があれば明記する
      • ex. 仕様変更が発生した場合は、当該箇所の旧文言を「更新履歴」シートに転記しておく。そのうえで、修正した文言は赤字に設定する
  • 削除・凍結の要領
    • そのドキュメントが必要なくなる (ファイルごと削除しても良くなる) タイミングがあれば、それを明記する。削除する予定がない場合も、その旨を記載する
      • ex. この「検討事項一覧」資料は、一覧に挙がった内容全てが「要件一覧」もしくは「課題一覧」に転記された後は、不要になる (削除しても良い)
      • ex. この画面仕様書は、改修の度に更新し続けていくため、システム自体が廃止されるまで削除してはならない
    • ファイルごと削除しないまでも、それ以降更新しなくなるタイミングがあれば記載する
      • ex. この「設計課題一覧」は、設計フェーズが完了した時点で凍結し、以降は更新してはならない。未完了の課題が残った場合も、本ファイルは更新せず、実装フェーズにて「実装課題一覧」に転記し運用する

ドキュメント作成で心掛けること

  • 読み手に無配慮なモノを残さない・作らない
    • 以下に色々書いてることを抽象化するとこういうこと
    • 読み手に「読解するコスト」をかけさせない文章が、良い文章。読む手間を省くために書く手間をかける
  • 5W1H を漏れなく記す
    • 一文ごとに、5W1H のどれが記載されていて、どれが抜けているかを確認する
    • 「記載を省略しても良い場合」はない。どうしても時制が関係しなかったり、場所に関する情報が存在しない事柄の場合のみ
    • 内容によっては、5W1H にプラスして How Much (コスト) の情報も書いてあると良い
  • 理由、経緯を必ず書く
    • 5W1H の中の Why は、特に記載が抜けやすい。書こうとするとどうしても文章が長くなるため、面倒臭がって省略しがち
    • それでも省略せず、似たようなことでも、何度でも書くことで、「根拠」を示せる
    • 何を考慮し、どの選択肢をどうして選ばなかったのか、という情報はとても重要。うまく共有できていないと、設計時に外した選択肢を、実装担当者が有益だと勘違いして勝手に盛り込んでしまったりする
    • 経緯を記したドキュメントを一つ作って、全ての関連箇所からそのドキュメントへのリンクを貼って周知すると、省力化できる
  • 指示語を使わない
    • 「それ」「その時」「上記」など。どれだけ文章が長くなってもいいし、何度繰り返し記述することになっても良いので、指示語を使わないことを優先する
    • 「去年」「先週」なども指示語。正確な日付を書く
  • 表記・表現を揃える
    • 英数字の全角・半角や、同じ単語をひらがな・カタカナ・漢字でデタラメに表記しないこと
      • その単語で検索 (Grep) しても全てがヒットしなくなり、それが影響範囲調査や修正対象調査の時に新たなバグを生む原因になる
    • 同じ意味なのに異なる言葉を使わない
      • ex. 「サブフォルダ」と「子ディレクトリ」など
    • 表記・表現を揃えるためには、予め「辞書」を作り、「採用する単語」「似ているが使わない単語」を明記し、チーム内での表現統一を図る
  • 規則性をもたせる
    • フォーマットは一定の範囲で揃える
    • 「システム」を主語に能動態で書くのか、それとも受動態で書くのか、といった体裁も揃える
    • その場しのぎで例外的な書き方をしたりしない
    • 規則を守らせやすくするには:規則の適用範囲を小さく保つ
      • 設計段階で「ドキュメントを書く時のルール」を定めると、テスト仕様書のフォーマットを作り始めた時に、ルールが上手く合わないことが出てきたりする
      • 「全てのドキュメントに適用するルール」を作るのではなく、「設計書で守るべき規則」「テスト仕様書で守るべき規則」という風に、規則の適用範囲を一定の領域に絞ると良い
      • 分割したそれぞれの領域で似たようなルールが存在する時は、なるべく同じ基準にしておきたいが、無理に統一しようとせず、また「共通ルール」といった資料を作らないようにする
  • 体言止めで書かない
    • 動詞が不明瞭になり、それが要件の勘違いなどに繋がるため
  • 日付は年・西暦から書く
    • 西暦の情報がないと、翌年読んだ時にいつの情報か分からなくなる

Excel で書く場合の定石

  • ブック、シートの「既定のスタイル」でデフォルトのフォント、スタイルを指定しておく
    • シートを全選択してフォントを変更するのはダメ
    • セルのサイズは「既定のフォント」から決まる。シートを全選択したりしても、結局は「セルごとにフォントを変えた」のと同じ状態なので、印刷時に見切れるなどの不具合が出がち
  • 垂直方向は上揃えをデフォルトにする
    • 表の中で折り返し表示するセルが混在したりする時も、上揃えにしてあれば、文章の1文字目の位置が揃って読みやすくなる
  • 空のシートを残しておかない
    • そのシートに意味があるのかと勘違いさせる
    • 「新規作成時のシート数」を「1」にしておくと良いかも
  • 「セルの結合 + 折り返して表示」は基本的に使用しない
    • 結合したセル内で「折り返して表示」がしてあっても、セルの高さの「自動調整」が正しく効かない (Excel の仕様)
    • セル結合は見出し行ぐらいに留めておく
  • プロポーショナルフォントは「メイリオ」を使うのがオススメ
    • 次点は「Meiryo UI」「游ゴシック」あたり。Windows の游ゴシック Regular ウェイトは細すぎるが…
    • 「MS P ゴシック」「MS P 明朝」は、印刷プレビュー・印刷時にフォントが大きめに表示されるので、文字切れが発生しやすい
    • メイリオは印刷プレビュー・印刷時にフォントが少し小さめに表示されるので、逆にゆとりができ、文字切れがほぼ起こらない
    • また、メイリオは全角文字が等幅なので、半角文字が登場しない場合は等幅フォントのように利用できる
  • 「条件付き書式」は行追加で定義が破損しやすいので多用しない
    • 条件付き書式の範囲内の行列をコピーし、「コピーしたセルの挿入」を使って貼り付けると定義を維持できる。…が、そもそもこういった条件付き書式の仕様を理解している人間が少ない
      • マクロで整形したら?とも思うが、条件付き書式をマクロで制御するのは結構大変。費用対効果に合わない
    • 条件付き書式は大抵色付けのために使用するだろうが、「色だけで何かを表現しようとしない」定石と照らし合わせると、そもそも多用することは推奨されない
      • 色分けがなくても理解できる別の形で表現する
  • 「入力規則」の「リスト」を使う時は、値のマスタを用意して「名前の定義」を使う
    • リストの定義に選択肢をベタ書きしてしまうと、項目の増減時にメンテしづらくなる
    • 「マスタ」シートなどを用意し、その項目の意味を併記する形で表にしておき、「名前の定義」を使うと、分かりやすくなる
  • ハイパーリンクは HYPERLINK() 関数で書く
    • 「ハイパーリンクの作成」でローカルや共有ドライブのパスを指定すると、ファイルを移動させた時にパスが壊れやすい
    • HYPERLINK() 関数はリンクパスを文字列で控えているので、ファイルを移動させたりしてもパスが壊れない
  • 罫線は「実線」のみを使い、他の罫線はなるべく使わない
    • セルごとに4辺の罫線情報を持っており、辺が隣接する2つのセルで異なる罫線情報を持っている場合は「罫線の種類」に基づく優先順位に沿って罫線が表示される。…とかいう罫線の仕様を知らずに使っていると、罫線が崩れたドキュメントを作りやすい
    • 「外枠は実線、内側は点線」のような罫線の設定はよく見かけて、確かに見やすいこともあるが、メンテナンス性が悪い
    • 余計な罫線を使わず、表全体を選択して実線を適用するだけ、と決めておけば、作成が楽になる
  • 表は「No」欄を必ず作る
    • 単なる行番号の表現として。コレがあると読み合わせの際に該当箇所を共有しやすい
    • シートの行番号は印刷されないから、必ず用意しておく
    • あくまでも行番号なので、「成果物 ID」や「テストケース No」などの項番とは別にしておく
      • 「成果物 ID」などは行追加・行削除によって項番がズレると面倒なことになるモノ。こうした項番は、数式などで表現せず、面倒でもベタ書きした方が良い
    • 単純な ROW() 関数だと、行追加などの変更に弱いので、以下の数式を利用する
      • =IFERROR(MAX(INDIRECT(ADDRESS(1,COLUMN())):INDIRECT(ADDRESS(ROW()-1,COLUMN())))+1,1)
  • 「文字色」や「セルの背景色」など、色分けで何かを表現しようとしない
    • 「文字色」や「セルの背景色」は検索ができない
    • 白黒で印刷された場合にも意味が通じるよう、数式を使うなどして文字列で表現することが望ましい
  • 「空欄」で何かを表現しようとしない
    • 空欄は「未入力」なのか「書き忘れ」なのか「何も問題がなかった結果」なのか、という区別が付かない
    • 特に何も記すつもりがない場合も、ハイフンを記載するなどして、明確に「何もない」ことを表現した方が分かりやすく、混乱が生じにくくなる
  • シート名を必ず書く
    • シート名によって、「記載範囲」を定めることになる
    • 今のところ1シートしかない場合であっても必ず書く
  • 日付の書式設定は「YYYY-MM-DD」か「yyyy-mm-dd」にする
    • ゼロパディングしてアラインメントを揃えると、桁の読み違えなどが起こりにくい
  • 複雑な数式が登場したり、集計したりする場合は、1シート・1セルで計算しきろうとしない
    • Excel がデフォルトで3シート用意しているのは、「元データのシート (入力)」「計算するシート (処理)」「結果のみを配置するシート (出力)」という使い方を想定しているため
    • 複雑な数式は、途中経過のセルを用意するなどして、一つひとつのセルの数式がシンプルになるよう心掛ける
    • 数式を見て他の人が検算 (レビュー) できるように作ること。計算過程が読み解けないと、ミスがあった時に調べきれない
  • 印刷時はブック名とページ番号、印刷する日時をヘッダ・フッタに記す
    • 紙資料が混ざった時に整理しやすくするため

言葉べからず集

  • タイトルに「〜について」を使わない
    • 中にどんなことが書いてあるのか推測できない
    • 記載範囲が広すぎる。もっと狭めておかないと「神クラス」ならぬ「神ドキュメント」になる
  • 「〜することができる」→「〜できる」で良い
  • 「〜ということ」→「こと」の多用を避ける
You can’t perform that action at this time.