設計の理論
工学では現状、「設計図とは何か?」といった理論は存在しません。情報工学でも、「IT企業の仕様書をどう書くか?」という書籍は、ほとんどありません。大学生向けの情報工学の参考書でも、まず触れられてない分野です。
本ページでは現状では参照していない文献ですが(2022年2月11日)、設計の理論を紹介していると思われる関連文献として『岩波講座 現代工学の基礎』があります。ある程度、設計についての抽象的な説明があるかもしれません(たとえば『岩波講座 現代工学の基礎〈1〉設計の方法論』(2000/5/10)あたり)。 しかし岩波のこの本はそんなに厚くないし、ソフトウェアも含めては説明していなかったかもしれません(手元にないので確認できません)。
ITの場合、ビルド手順の記録が必要

集団でソフトウェアを作るとき、そのソフトウェアのビルド方法を仕様書に書かないといけません。(これは製造業の設計図などには無い、IT業界の独自の事情です。)
ITの場合、ビルド手順の記録が必要

ビルドとは、実行ファイルを作ることです。
ITの場合、ビルド手順の記録が必要

Visual Studio などのソフトウェア開発環境ツールは大抵、ビルド機能もあるので、最低限、作者が実際に使用した開発ツールを書いておく必要があります。ビルドに必要としたソフトウェア(ビルド実行ソフトや、必要なライブラリ)、ビルドのためのコマンドや操作手順なども、ひとつひとつ詳細に書くべきです。
ITの場合、ビルド手順の記録が必要

実際に自分がそれらビルド手順のとおりにソフトウェアだけをインストールと設定を試してみて、もしその手順の指定に従えば(従うのが知識的に簡単かどうかはともかく)、とりあえずビルドできて、実行ファイルを生成できる程度には、書く必要があります。
ITの場合、ビルド手順の記録が必要

ソースコード公開サイトなどのプログラムを見ると、説明書を見てもどこにもビルド方法や実行環境が書かれておらず、ビルドできずに使いようのないコードが時々あります。ビルド不可能ではあまり有意義なソースとは言えないでしょう。
必要な書類

一般のIT業界や製造業の場合、集団作業で必要となる書類は、主に下記のセットでしょう(編集者Sの推測)。
必要な書類

設計図とは完成図のことです。
必要な書類

さて、一般のIT企業や製造業では上記の設計図~参考資料に加え、必要に応じて「説明書」、などを加える場合もあります(業界や会社によっては、説明書は上記セットとは別の本棚などに分離する場合もある)。この4〜5点セットの書類を、集団作業の便宜のために、将来にわたって残していきます。(土建や製造業などの堅い業界の場合は、「設計図書」(せっけい としょ)、などの名前で管理されることもあります)
必要な書類

娯楽産業ではない一般のIT企業や製造業でも、製品の企画に至った経緯を記した書類を、大元のアイデアを考えた会社の側では残しています。(ただし一般企業の場合、社内プレゼン用資料の流用の場合もある)。上記セット一覧のうちの「設計図」はゲーム業界では「仕様書」に対応しており、「企画に至った経緯を示した書類」は「企画書」に対応しています。一般企業では書類の名前は、「企画書」ではない場合も多く、業界や会社によって異なります。
必要な書類

企画書だけでなく、マトモな科学論文とかでも、既存品と今回の製品とはどう違うのかという構成が好まれます。つまり、論文なら「何を新発見したのか? → いままでの理論ではどうだったか?それと今回の新発見とでは何が違うか? → 発見のプロセスや詳細など」といった構成が、マトモな科学論文のあるべき構成です。
必要な書類

また、メンテナンスのための図面として、「フロー図」とか「モジュール図」や「システム図」等、設計図としての目的でない将来的なメンテナンス改修などを見越して作成される図を、保存しておく必要があります。
必要な書類

一般IT業界の仕様書の書き方の本やwebサイトを見ると、「要件定義書」「内部設計書」「外部設計書」「ネットワーク図」「業務フロー図」「インターフェース設計書」「モジュール設計書」などの色々な書類・図面がありますが、発注元で最低限必要なのは上記4点セット(完成予想図、メンテ用資料、企画書類、外部資料)でしょう。IT業界特有の設計書類も、完成予想図またはメンテ用資料を作成するため手段に過ぎません。
「設計図」とは完成図である

では「設計図」とは何かというと、製造業の場合での「設計図」の意味を説明すると、それは「完成予想図」です。「完成予想図」というところがポイントで、実は生産方法などは指定していないのです。なので設計図だけでは、実は何も生産できないのです。
「設計図」とは完成図である

なので設計図に加えて、現場で必要な生産方法の技術をもった技術者が、さらに必要です。なので、設計図はあくまで、最低限必要な情報でしかないのです。実際には、設計図以外にも、生産方法についてのさまざまな情報が必要です。
「設計図」とは完成図である

ですが、どこの業界でも、生産方法については図面化しないか、たとえノウハウを部分的に文書化していても社外秘にしていて非公表なのが通常です。
「設計図」とは完成図である

IT業界でも、あるソフト製品のプログラミングの具体的なノウハウについては、その製品の「仕様書」には記載されないのが通常です。
「設計図」とは完成図である

完成予想図として「部品図として、このような寸法(各部の長さ)・形状・材料をもった部品を図面の指定どおりに作れば、あとは組立図に部品どうしの相互位置が書いてあるので、(組立図の)その位置指定とおりに取り付ければ、必ず完成しますよ」
「設計図」とは完成図である

という状態にまで、部品図と組立図の状態をそれぞれ完成予想図の形で書き上げていくのが、図面を書くという事です。
「設計図」とは完成図である

技術的の企業でいう「設計図」の意味は、おおむね、こういう意味です。
「設計図」とは完成図である

もし、納品される品物が仕様を満たしてない場合、けっして合格品としてはいけず(つまり「検収」してはいけず)、(発注者は)協力会社に作り直しを要求します。この仕様違反のさいの作り直し要求はIT業界にかぎらず製造業でもどこでも、受け入れ検査は通常、そういう仕組みです。
「設計図」とは完成図である

ソフトウェアを作る場合も、最終的に製品の完成の段階では、最低限このような水準にまで、設計図を作りこんでいきましょう。(ただし、ソフトウェアには「寸法」など形状の条件は無いので、そこはアルゴリズム的な条件に意味を読み替えること。)
「設計図」とは完成図である

製造業では図面をもとに見積もりをします。基本的に技術系の業界では、設計図をもとに見積もりが行われるます。
「設計図」とは完成図である

学生は企業社会を知らないと思うので説明しますが、コンピュータ業界にかぎらず、そもそも製造業なども含む技術系の業界で、設計から生産までの流れがどういう工程で行われているか、説明します。
「設計図」とは完成図である

まず、なにかの設計図では、具体的な生産方法は指示しません。たとえば、組み立てた後の形状がどうなってるかは組立図(くみたてず)に描いても、しかし、「どうやれば組み立てられるか?」とかの情報は一切、そういう事については『設計図』では指示しません。
「設計図」とは完成図である

ともかく、なにかの設計図は通常、その製品の完成図である必要があります。製造業で「図面」と呼ばれているものは、こういった具体的な完成予想図のことです。
「設計図」とは完成図である

そして、その完成図はいくつもの部品から成り立っているのが普通なので、完成品をいくつかモジュールごとに分解した部品図(ぶひんず)をいくつも作成して、それぞれの作成担当の作業者に渡します。
「設計図」とは完成図である

こうすることで、分業もしやすくなり、一石二鳥です。
「設計図」とは完成図である

基本としては、設計図とは、設計図だけを見ても、あいまいさの無い状態で完成品の満たすべき具体的な条件が分かるようにしなければなりません。
「設計図」とは完成図である

さて、製造業などでも、「図面」という完成予想図があります。
「設計図」とは完成図である

よく、IT業界でいう「現場で見つかった仕様書の不具合を仕様書にフィードバックする」とか言う表現は、おそらく完成予想図のような書類のことを指していると思います。
「設計図」とは完成図である

なぜなら製造業でもフィードバックは図面に対して行います。なので、製造中に不具合が見つかれば、どんどんと図面が改訂されてゆくし、そのために設計者は現場に立ち会うし、場合によっては設計者みずからが製造もしていきます。
「設計図」とは完成図である

技術系の業界では一般に、書類で作業指示を出すときに、いちいち、けっして具体的に、「作業員であるアナタは、○○のコンピュータの△△ボタンを押して、××をしてください」のような指示は出さないです。
「設計図」とは完成図である

指示はそう出すのではなく、図面のような完成予想図(ただし決定稿)を出して、「この完成予想図のとおりになるように作っておいてください。」というような指示が出ます。
「設計図」とは完成図である

さて、IT業界の場合、末端の部品プログラム完成予想図を描く前に、普通の設計では既にフローチャート図または状態遷移図などといった、全体的なシステムの図面を書くのが望ましいとされています。(以降の説明では、言い回しの省略のため、フローチャート図または状態遷移図を単に『フロー図』または『フローチャート図』と略記する。)
「設計図」とは完成図である

なので、もし横断的な説明をしたければ、このフローチャート図を作るとき、このフローチャート側に説明を追加するとか、あるいは、フローチャート図を参照する形で別途の参考図を追加するとかすれば、良いかもしれません。
「設計図」とは完成図である

こうすれば、もし末端部品プログラムを訂正することになっても、訂正の必要のある図面は、末端プログラム図面と、その直接の上流のフロー図あるいはフロー別途参考図だけのたった2枚に限定できますので、訂正の手間を減らせるので効率的です。
「設計図」とは完成図である

なお、もしかしたらIT業界でも、状態遷移図やフローチャートを描かないで設計する事態も企業によっては横行しているかもしれませんが(原理的には、状態遷移図やフローチャート図が無くても、エクセルなどで作成した部品プログラム仕様とその組み立て仕様のエクセル形式の完成予想図だけでも、原理的にはソフト設計できてしまう)、しかし、こういう状態遷移図などの画像での説明を省いた設計では設計ミスが発生しやすく、結局、再設計などの手間が掛かってしまうのがオチです。
「設計図」とは完成図である

なお、一枚の仕様書の中では、内容の重複はオッケーです。
「設計図」とは完成図である

たとえば、機能の似たモノを2個つくるとき、
「設計図」とは完成図である

2個目の説明では、「○○については△△と同じ」のように、「~~~と同じ」というふうに説明できるから、です。製造業でも、一枚の図面に正面図と側面図の2方向の図のある場合、側面図に参照値として正面図の値を書くと、正面図の設計変更にともない、ときどき側面図にある参照値を修正し忘れるミスがあります。)
「設計図」とは完成図である

なので、よほど仕組みの複雑な難しい製品でないかぎり、なるべく2回目以降の説明では具体的内容は書かないのでおくのが、設計の図面では修正モレを防げるので安全です。
「設計図」とは完成図である

ただし、これはあくまで、設計図面の書き方です。教本や指導書などの書き方とは、設計図面の書き方は、違います。もし、新人むけの指導書や教科書・教本を書く場合には、やや重複のある内容でも何度も説明して覚えさせましょう。
要求事項書

要求事項は、「○○してもらいたい」という指定も必要ですが、ソレとは別に、できれば、「なんの目的で、そういう指定をしているか?」などの理由も書いてあると、ニュアンスが正確に伝わるので、伝達ミスなども減ります。
要求事項書

企業秘密などで無いかぎり、できるだけ、目的も平気したほうが良いでしょう。
要求事項書

要求事項の書類には、要求には理由も併記するのが望ましいと指導されているようです。
要求事項書

さて、一般IT企業で要求事項書の話題に戻るとして、また、意外と伝達側が設計ミスをする場合もあるので、目的も書面で伝えておくことにより、相手先の人が、気を聞かして検証してくれます(べつにボランティアで検証してくれるわけではなく、どっちみち相手先が設計中に結果的に検証することになるで、だったら要求事項に目的も書いておいたほうが効率的になる)。
要求事項書

なんども指摘するが、「要求事項」だの「設計図」だの何種類も作る書類セットの書き方では、説明が重なって多いぶんには問題ないのです。(ただし、要点などを抜き出した簡略版の説明も必要。)
要求事項書

大は小を兼ねます。
要求事項書

なお、社会人の情報伝達では、結論を先に言うのがマナーなので(詳しくは『中学校国語/現代文/報告書の書き方』)、要求を先に伝えてから、理由を直後に伝えます。つまり、文章のテンプレートとしては、
要求事項書

のような順番になります。
要求事項書

設計図の各書類は一般的に外部には非公開なので、書類セットくらいでしか体系的な説明をできないので、むしろ別書類にて説明の重複などがあって相互検証できるくらいのほうが、安全なのです。なお、要求事項の段階では、あまり細かく事項書を作りすぎずに、そのぶん実際のプログラムの開発を早めましょう。
データ台帳

重要なことは、一般のソフトウェア開発などでの実務では、なんらかの特殊な数値データが組み込まれている場合、台帳と実物プログラムとによってダブルチェックをするという事です。(ゲームだけでなく、製造業の組み込みソフト開発などでも、台帳などによってダブルチェックをしています。)
データ台帳

IT業界では、ダブルチェックを軽視している人が多いですが(たとえば電卓とパソコンソフトとの計算結果のダブルチェックを批判する言説がネットに多い)、そういうのは製造業や組み込み業界などでの実務を知らない知ったかぶりのタワゴトなので無視しましょう。
データ台帳

マトモな業界では、プログラムの検証のため、そのソフト以外およびそのソフトを動かしているハードウェアとは別のデバイス(電卓でも良い)を使って、ダブルチェックをするのが常識です。(※この常識には出典を出せませんが(企業秘密などに関わるので)、しかしダブルチェックを軽視する側の主張も満足な出典を出せていないので、対抗的にこの文を残します。)
データ台帳

さて、入力されたハズのデータの台帳のような内容の一覧の書類が、一般の技術系企業では必要です。業界で「台帳」と言うのかは知りません。名前が無いと困るので、とりあえず土木工学ではこういうのを「○○台帳」というので、それに習って「データ台帳」という題名を本セクションでは、つけているだけです。なので、IT企業では別の呼び名かもしれません。
多項式近似

測定値などで、入力変数が一変数なら、エクセルなどを用いて多項式近似が出来ます。
多項式近似

一般にIT業界での実務の多項式近似では、原理的には9次でも20次でも、どんなに次数が高くても(おそらく int 整数型の限界くらいまで)計算できてしまいますが、
多項式近似

しかしIT業界などの実務では人間の検算などの手間を減らすために、なるべく、せいぜい2次式や3次式といった、低めの次数におさえて利用するのが、IT企業では普通です。
多項式近似

もし先端科学のための多項式近似なら、9次を超えるような多項式近似をするような場合もありますが、しかし、一般の企業では、そこまでの多項式近似は不要ですし、むしろ検算などの管理の手間が増えるので、9次のような多すぎる次数は嫌われますので、なるべく2次ていどに抑えましょう。
バグあると人の死ぬ業界

ゲームではバグがあっても、人は死にません(過労自殺などを除けば)。なので、アイデアが思いついたら、どんどんとプロトタイプで試してみましょう。
バグあると人の死ぬ業界

ですが、他の業界だと、バグがあると人が死ぬ場合もあります。たとえば、製造業での、組み込み機器などがそうです。
バグあると人の死ぬ業界

書籍で紹介されている事例だと『メタルカラーの時代』シリーズ(山根一眞(やまね かずま)による取材)で、 「日本ユニシス」というIT企業がかつて、提携している別企業のNC工作機械に向けた組み込みソフトの開発で(組み込みソフト部分をユニシスが開発)、開発テスト中のバグにより工作機械の刃物が本体にぶつかって折れて飛んできて、あやうく人が死ぬところだった、 ・・・という感じの事例がインタビュー先のプログラマから紹介されています。 それまで日本ユニシスおよびその担当プログラマーでは、組み込みの仕事はほとんど扱わずに、どちらかというとIT業界内での顧客を仕事をしていたので、そういう人が死にそうな事例に経験することがなかったので、製造業の組み込みソフトでは特にバグおよびバグ予防に対する考えをIT業界内の仕事とは変えなければならない必要があることに気づかされた、とユニシスの技術者はインタビューで述懐しています。
履歴の管理

一般のIT企業でいう仕事の「仕様書」では、開発前の段階で書いた要件定義書や設計図(完成予想図)やコード解説書など」を、ソフト完成後にも残す必要があります。
履歴の管理

なぜなら、開発前~開発中の経緯を、上司や他部署に事後的に報告したり、のちに入社してくる後輩などに教育としてソフト開発時の出来事を教えるためです。
履歴の管理

このため、こういった仕事の書類には、著者や、著作・改訂の日時(「改訂日: 2018年8月30日」)や改訂者(「改訂者: 山田太郎」)などの履歴(りれき)も記載する必要もあります。
履歴の管理

のようになります。(企業では、こういうページのパソコンでの文書管理は、エクセルなどの表形式データになってるのが普通。)
履歴の管理

さらに改訂の際には、それぞれの版の改訂内容の要約を書く必要すら、あります。
履歴の管理

アマチュアの場合なら、『メモ帳』アプリなどで説明する場合もあるかもしれないので、たとえば
履歴の管理

のようにアレンジする必要があるかもしれません。
履歴の管理

アマチュアのゲーム製作の場合、エクセルまでは不要でしょう。
ファイル名の冒頭番号

ゲームを例に説明します。
ファイル名の冒頭番号

ゲーム産業に限ったことではないのですが、企業でのパソコン内での、ファイル名やフォルダ名の管理手法として、たとえば何かの説明書きのファイルがいくつもある場合、
ファイル名の冒頭番号

などのように番号順をつけて命名することもあります。「01_キャラクター設定」でひとつのフォルダ名です。なぜこのように番号を冒頭につけるかというと、もしパソコン上で名前順に並び替えたときに、必ず狙った順番どおりにさせるためです。
ファイル名の冒頭番号

そして、たとえば「キャラクター設定」フォルダ内に、さらに
ファイル名の冒頭番号

のように、さらに 番号づけの設定があることもあります。
ファイル名の冒頭番号

たとえば、「ゴンザレス」というキャラが主人公のゲームの場合、彼が最初に来てもらわないと困るわけです。もし番号が冒頭に無いと、「ゴンザレス」よりも「アルベルト」のほうが五十音順では先に来てしまいます。
ファイル名の冒頭番号

しかし、上記のように番号を冒頭につける方式を採用することで、あとでどんな名前の新キャラクターを追加しようが、必ずファイル検索の名前順検索では「ゴンザレス」が最初に来るようになるのです。
ファイル名の冒頭番号

なお、業務用のファイルでは一般的に、冒頭番号と項目名とが別々のものであることを強調するために、半角スペースを使わずにアンダーバー「_」を使うのが一般的です。
ファイル名の冒頭番号

IT企業に限らず製造業でも、たとえば図面ファイルでは
ファイル名の冒頭番号

などと、冒頭番号ごと名前をつけてフォルダ管理するのが一般的です。
ファイル名の冒頭番号

フリーソフトのファイル構成などでも、本ページはゲーム教科書なのでゲームに置き換えて説明しますが、
ファイル名の冒頭番号

のようなファイル構成のフリーソフトも時々、見かけます。
説明書

フリーゲームなどは、あまり説明書が細かくかかれないので、気にする必要はないでしょうが、一般IT企業のソフトウェア説明書や製造業の組み込みソフトなどは、もっと細かく一通りの操作方法を説明します。
説明書

イメージしやすさの都合で本ページでは、製造業などの組み込みソフトを例に、説明書の書き方を説明します。
説明書

なんと、組み込みソフトの説明書を書くためには、操作テストが必要です。
説明書

だから例えば工場の生産ライン用の設備に組み込まれてる組み込みソフトの説明書なら、その説明書の文面は、工場で下書きしてるわけです。
説明書

オフィスで下書きするのではなく、工場で下書きするのです。なので、工場にノートブック(文房具)と筆記用具(要・赤ペン)を持ち込んで、そこで説明書の文面を下書きするわけです。
説明書

たいていの新人は、実機での操作テストに気が引けがちです。
説明書

実機で操作テストばかりしてると「周囲の先輩から『この新人は書類も読まずに実機をいじって遊んでる』と周囲に見られるんじゃないか?」と不安になったりとかして、実機によるテストを遠慮しがちです。また、仕様書は読んでて勉強になりますので、ついつい仕様書ばかり読みがちで、テストを遠慮しがちです。
説明書

しかし、それは新人特有のよくある勘違いなのです。説明書を書く場合にも、実機でテストプレイをするべきなのです。
説明書

なので、下書きが終わったら、さっさと実機テストをするべきなのです。
説明書

まず、仕様書などをもとに、説明書の大まかな章や節などの構成を、仮決めします。
説明書

大まかなページ数などの仮決めのために、仕方なく仕様書を見ながら、仕様書から想定されるハズの操作方法を書きます。
説明書

この下書きは、これはこれで必要であり、あとの操作テスト時にチェックすべき項目を示したチェックリスト的な意味合いもあるので、とりあえず、実機プレイなしですが下書きをします。
説明書

ですが、この想定した操作方法は、まだ何のテストもしてないので、高確率でミスが含まれています。
説明書

なので、下書きした説明書のプロトタイプと筆記用具(赤ペン)を持ちながら、実機のある現場に移動して、到着したら実機で説明書どおりにテストプレイしながら(絶対に説明書を見ながら、杓子定規に説明書どおりにプレイします)、実機操作中に発見した説明書のミスを、赤ペンで下書き説明書に、追記でメモ書きしていくワケです。
説明書

このように仕様書ばかり読んでないで、さっさとテストします。
説明書

だから、説明書を書くオフィスは、そういうテストが気軽にできる環境の近くに存在する必要があります。
説明書

また、組み込みソフトの説明書を書く技術者は、工場の組み込みソフトを書くなら、技術書の服装としてはブルーカラーの作業着で仕事してるわけです(背広ではないです)。作業着でないと原則、現場に入れないので
説明書

組み込みソフトは、機械などに組み込まれてるわけですから、安全が確保されていて可能な限り、仮想化などではなく、実機でテストします。 (仮想化でテストすると二度手間になります。なので可能なら最初から実機でテストしたほうが早いです。)
説明書

このような仕事を、よく新人がやらされます。
説明書

新人は消費者目線に近いので、どこの業界でも、新人がよくテスターにさせられることが多いのです。
説明書

同様の理由(消費者目線)で、説明書を書く仕事も、どこの業界でも、新人がよく説明書を書かされます。
説明書

子供向けの玩具で電子玩具の説明書などだと、場合によっては説明書の文面が子供口調(「~だよっ!」とか「~だね!」みたいな口調)で説明が書かれていたりしますが、けっして説明書を書くお仕事が子供の学校の図工みたいな作り方をしてるワケではないでしょうし、おそらくは実際の執筆手順は上記の組み込みソフトの説明書のような感じの手順で説明書を書いていってると思われます。説明書の口調という表面にダマされないようにしましょう。
説明書

ああいう子供口調やら女口調の説明書は、集団作業の場合なら、下書きの段階での口調は、普通のビジネスマン的な書類の口調で書いているか、たとえ くだけた下書きの場合でも普通の大人のくだけた口調で下書きを書いているのであって、あとの工程で口調だけ入れ替えて子供口調や女口調に入れ替えるという手間を掛けていると思われます。けっしてイキナリ、子供口調とかで書類を書きはじめるわけではありません。
パラメータ調整の理論

たとえば機械設計の業界で昔から言われている教訓として(なるべく新規設計では)「材料と構造を同時に変えるな」というのがあり、日経クロステックのwebサイトでもそう紹介されています。引用元の日経クロステックの記事では「2つ以上のものを同時に変更するときは、組み合わせによる問題が起こりやすいことを示唆している」と指摘されています。
メンテナンス用の書類の概要

完成形をつくるだけの「設計図」的な「仕様書」だけでは、バグ発生時や設計ミス発生時などのさいの修理が不可能です。
メンテナンス用の書類の概要

また、ITソフトウェアなら、移植などの際に、もしソースコードだけしかなくて書類不足だと、「コードがどのように動いているのか?」を後任の人が把握できずに、移植困難になってしまうトラブルもあります。
メンテナンス用の書類の概要

前任者が会社を辞めてしまっている場合などもあるので、色々と書類が必要でしょう。こういうことから、もし下記のような資料が無いと、不具合の発生時に、修理のための設計変更で、どこをどうイジればいいか特定できず、困ります。
メンテナンス用の書類の概要

というか、残念ながらこういう資料の不足している職場は多く、なので日本のIT技術者は困っています。
メンテナンス用の書類の概要

上記書類のうち、特に「部品と機能の対応表」、「コード解説書」は、メンテナンス目的以外にも、設計図のチェックにも利用される。なので、そういう目的もあるので、ぜひ作成しておくのが望ましい。
メンテナンス用の書類の概要

「部品と機能の対応表」のことを、IT業界で何と言うのか、このページの著者は知りません。しかし、ともかくそういう対応表がないと、メンテナンスが後々に困難になります。
メンテナンス用の書類の概要

発売後の(一般のIT企業では)ソフトにも、修理・メンテナンスが不可能になる場合があります。
メンテナンス用の書類の概要

そのため、製造業などの組み込みソフトなど、まともなIT業務では、ソースコードの内部構造・全体構造のコード解説書とでも言うべき書類があることが望ましいです。(特に名前は決まっていない。また、中小企業などでは作成しない場合もある)
メンテナンス用の書類の概要

一般のIT企業では「内部設計書」や「プログラム設計書」などの名前の場合もありますが、しかし既に設計図などで大まかな指定はできていますので、設計の時点では、これらの「設計書」が不要な場合も多くあります。
メンテナンス用の書類の概要

これらの書類の目的は、どちらかというと、設計よりも、後日に読み返したときのメモ書きです。主要な変数、主要な関数などは、第三者が、なんのドキュメントも無い状態でその意図を読み取るのは、なかなか手間が掛かります。なお、最終製品やあるいはコードだけから逆に設計書や設計図などを書き起こすことを「リバース・エンジニアリング」と言います。リバース・エンジニアリングは、本来なら、後任者などには、させるべきではないのです。
メンテナンス用の書類の概要

大目的として、完成後のメンテナンスなどの際に、リバース・エンジニアリングという手間のとても掛かる作業を、けっして後任者にしないでも済むように書類を残すのが、正しい書類作成および書類管理のありかたです。これが、前提の大目的です。これさえ押さえてくれれば、ほぼこのページで言いたいことは尽くされています。このページの残りの説明は、単にイメージを具体化するためのケーススタディです。
メンテナンス用の書類の概要

会社でリバース・エンジニアリングの手間の発生が起きるのは、経営者にとっても時間と予算のロスでしょう。また、リバース・エンジニアリングをさせられる側である社員も、利益を生み出すわけではない作業に時間を多く取られ、とても負担です。なのでとにかく、リバース・エンジニアリングの発生予防が必要です。
メンテナンス用の書類の概要

で、具体的にどうすればいいかというと、リバース・エンジニアリングの発生を防ぐためには、なんらかの方法で、少なくとも主要な変数や関数と、その設計意図の対応表のようなものが必要です。
メンテナンス用の書類の概要

(完成図である)設計図だけでは、このような機能の解説をするのは不可能または困難なので、さらに変数・関数と、設計意図との、対応表のようなものが必要です。この対応表のようなもののことを本wikiでは「コード解説書」と呼んでいます(IT業界で何と言うのか知りません)。(設計図だけでも機能の解説を出来ているなら、その部分は解説書に書く必要はありません。)
メンテナンス用の書類の概要

要するに、機能と部品との対応表も残すべきだという亊です。「この部品、どの機能に対応してるの?」ってのが分かればいいのです。
メンテナンス用の書類の概要

異業種の例ですが、下記の2つの回路の図面を見比べてください。
メンテナンス用の書類の概要

どう比べても、右の「フロー図」のほうが、仕組みが分かりやすいでしょう。もし回路設計の専門外の素人が上記の回路図面を見ても、フロー図のほうなら機能が一目瞭然です。
メンテナンス用の書類の概要

このように、部品と機能を比べる書類があれば、とても後任者がラクになります。
メンテナンス用の書類の概要

また、このような部品と機能の対応の書類を作っておくことで、設計ミスの防止にもつながります。
メンテナンス用の書類の概要

上記の図面の例は、電気回路の設計の業界のハナシなので、ITではないですが、ともかく、こういう部品と機能の対応表があると、仕事がいいカンジです。
メンテナンス用の書類の概要

「フロー図」だの「コード解説書」などの名前はどうでもいいです。重要なのは、部品と機能の対応表を残しておけ、という事です。
メンテナンス用の書類の概要

逆に言うと、部品と機能の対応が分からないような書類ばかりを作っていても、無駄です。
メンテナンス用の書類の概要

けっして、やみくもに「○○設計書」のような名前の書類をいくつも残すのではないべきです。目的である、「部品と機能の対応表」を忘れないようにしましょう。
メンテナンス用の書類の概要

IT業界でこういう書類を残しているか知りませんが、少なくとも電子回路の業界では、こういう書類を残しています。けっして、(ブラック企業だらけだと悪評高い)日本IT企業の習慣のマネではなく、世界に冠たる競争力をもつ日本のB to Bの電子機器の製造業の手法をマネしましょう。
メンテナンス用の書類の概要

一般の企業でのITソフトは、発売後から10年後や20年後にもメンテナンス等が必要な場合があるので、コードの全体構造の解説書が必要なのです。たかが1~2年で流行の廃れるソフトの管理手法なんか、手本にしてはいけません。
メンテナンス用の書類の概要

コード解説書を書かない場合、それでも将来的なリバースエンジニアリング予防のために解説を残したい場合には、おそらくですが、代わりに「仕様書」などの既存の種類に流用で、変数名や関数などの指定を記載したりする必要が生じるかもしれません。ソフトウェアの設計図(完成予想図)はその性質上、解説などはあまり長く書けません。それはそれで一つの方法です。勤務先などに応じて、うまく方法を選んでください。
メンテナンス用の書類の概要

しかし、個人製作ソフトの場合、仕様書は無いのが普通なので、簡易的にコード解説書を書いたほうが早いかもしれません。プログラミングは、仕事や学業などの都合で中断される場合もありますが、再開後に、中断前のアイデアなどを思い出すためにも、コード解説書は書かれていると便利です。(コレがないと、時間が経つと、ほぼ作業内容を忘れる。)
メンテナンス用の書類の概要

さて、経団連企業などの東証一部の上場企業のIT業界の人が「仕様書を書かないと、あとでコードの仕組みを忘れる」とか言ってるのは、きっと、このコード解説書のことでしょう。経団連発言の時代的な文脈的に、けっして要件定義書とか完成予想図とかのことではないハズなので、勘違いしないようにしましょう。
メンテナンス用の書類の概要

このコード解説書の書き方には、けっして、決まった書き方がありません(なので、市販の入門書では、紹介されてない)。ですが、ともかく、経団連企業とかの技術系企業の設計部門では、こういう書類も書くのが望ましいとされています。
メンテナンス用の書類の概要

重要なことは、コードのどの部分が、ソフトウェアのどのような機能を実現するために、何を構成しているかと言った情報を、コード解説書または仕様書などで残すことです。
メンテナンス用の書類の概要

システム構造を解説するには、要するに変数名や関数名や、モジュールが、設計図に示した設計意図にどう対応しているかを、記載できれば良いのです。こういった大目的をまず忘れないようにしましょう。
メンテナンス用の書類の概要

では、どうやったら、こういう解説をできるのかを、これから考えていきましょう。
メンテナンス用の書類の概要

ソフトウェア開発前には実際のシステム構造(プログラムをどういう仕組みにしたとか、変数名をどうつけたか、とか)を書くのが難しいので、ある程度、開発が進んでから、開発中にシステム構造を書くことになります。
メンテナンス用の書類の概要

このコード解説書には、決まった描き方がありません。(なので、一般むけの「仕様書の書き方」入門書では、紹介されていない。)
メンテナンス用の書類の概要

なお、この「コード解説書」書類の呼び名は特に決まっていません。呼び名が無いと不便なので、とりあえず「コード解説書」と呼ぶことにします。
メンテナンス用の書類の概要

まず、ソフトウェアのシステム構造を解説する場合、どのファイルがエントリポイント(コンパイル時に最初に呼び出されるファイル。Main関数などがある)なのか、そういうことから、コード解説書に書いてください。
メンテナンス用の書類の概要

C言語にはファイル分割という機能があり、ソースファイルを複数のファイルに分割できますので、実際のソフトウェアではファイルが何種類もできます。
メンテナンス用の書類の概要

なので、コード解説書にエントリポイントがどのファイルなのかを書いてないと、いちいち読者がファイルを開いて読まないと、どのファイルが最初に呼び出されるのかを理解できません。
メンテナンス用の書類の概要

ファイル分割されたファイルが幾つも(いくつも)ある場合、例えばゲームソフトだとして、ジャンルがRPGなら
メンテナンス用の書類の概要

などのようにファイルが幾つもある場合、
メンテナンス用の書類の概要

システム構造書に、
メンテナンス用の書類の概要

などのように、それらのファイルが何を処理しているのかを第三者が分かるように書いてください。また、なるべく箇条書きで書くのが、読みやすくて便利でしょう。
メンテナンス用の書類の概要

当たり前に残すべきメモのように思えるかもしれませんが、しかしこういったメモが残されてない職場は多くあります。悪い見本です。とにかく、瑣末なことでリバース・エンジニアリングを後任者にさせないように書類を残す習慣をつけましょう。
メンテナンス用の書類の概要

ダメな一般IT企業だと本当によくあるパターンで、ファイル解説の書類など何も残ってないのに自社アプリのファイルサーバーには「system.cpp」などの漠然とした名前のファイルだけがいくつもある場合が時々よくあり、「systemって何のシステムだよ・・・」と後任者があきれたくなるファイル名のプログラムがいくつもある場合、これは大変にリバース・エンジニアリングの手間を発生させる、プログラマーにとってイヤなパターンです。
メンテナンス用の書類の概要

暗黙の前提ですが、画面名やファイル名などの名前を決める際には、具体的な名前をつけるべきです。
メンテナンス用の書類の概要

書籍『ゲームプランナー入門 アイデア・企画書・仕様書の技術から就職まで』によると、ゲーム業界でもそう指導されています。
メンテナンス用の書類の概要

ゲーム業界に限らず、一般のIT業界でも同様に具体的に命名するべきでしょう。つまり、「file1.cpp」とか「a.cpp」みたいなファイル名は厳禁です。また変数名でも「b」とか「variable1」(英語でvariableとは「変数」という意味)みたいな変数名は避けてもらいたいです。
メンテナンス用の書類の概要

なお、一般企業では箇条書きの説明をするとき、よくエクセルなどの表形式で説明することもあります。
メンテナンス用の書類の概要

のような表形式でよく箇条書きが書かれます。
メンテナンス用の書類の概要

開発した原作者には、「ファイル名から予想がつくだろ?」と当然に思うことであっても、意外と、通じない場合がありますので、きちんとコード解説書に、ファイルの処理内容を文章で書くべきです。
メンテナンス用の書類の概要

例えば、RPGの「メニュー」と言われても、あなたは「道具」「装備」などの画面を思い浮かべても、ほかの人は、戦闘シーンの「戦う」「逃げる」などのコマンド画面を思い浮かべるかもしれませんし、あるいは会話イベントの「はい」「いいえ」などの返事の選択画面を思い浮かべるかもしれません。
メンテナンス用の書類の概要

また、「マップ」 map と言われても、あなたは「主人公が現在いる場所の周囲」を思い浮かべても、ほかの人は、道具「地図」を使うと画面表示される世界マップと、世界地図のなかでの、主人公のいる地方の位置を思い浮かべるかもしれません。
メンテナンス用の書類の概要

または、「洞窟などのダンジョンの構造が書かれた地図のような道具が、そのゲームの中にあるのでは?」とか想像する人もいます。
メンテナンス用の書類の概要

このほか、数学用語で「map」(日本語でいう写像(しゃぞう)のこと)という用語がありますので、それと混同される場合もあります。
メンテナンス用の書類の概要

このように、ファイル名だけだと、いろいろと想像されてしまいます。
メンテナンス用の書類の概要

なのでコード解説書を作る場合、もし仕様書側に解説が無い項目なら、そのファイルのソースコードを読まなくても理解できるように、きちんとファイル内容の要約を解説書に書きましょう。
メンテナンス用の書類の概要

このほか、どうしても「System.cpp」とかのような漠然とした名前のファイルがある場合、何のシステムなのか、わかるように書いてください。(そもそも、そういう漠然とした名前を避けたほう安全ですが。)
メンテナンス用の書類の概要

たとえばRPGを作るなら、
メンテナンス用の書類の概要

などのように、そのゲームで使うパラメーターについて、ひととおり、変数名と、その内容の要約を書いてください。
メンテナンス用の書類の概要

たとえ原作者には「当然だろ」と思えることであっても、他人には意外と通じません。
メンテナンス用の書類の概要

たとえば、「defence_power」と言われても、仮にアナタは「防御力」のことだと思っても、ある人は
メンテナンス用の書類の概要

とか、思うかもしれません。
メンテナンス用の書類の概要

また、防具の防御力と、人物の防御力とを、同じ変数にするか、違う変数にするのかどうかも、「defence_power」という名前だけでは分かりません。
メンテナンス用の書類の概要

でも「人物の防御力」というように要約があれば、「あっ、防具の防御力は、人物の防御力とは別の変数なんだな!」って分かります。
メンテナンス用の書類の概要

また、
メンテナンス用の書類の概要

のような、魔法のような非現実的なファンタジーを前提にしたパラメーターがある場合、そのパラメータが何に影響をするのか、仕様書のほかの部分に書いてください。
メンテナンス用の書類の概要

例えば、
メンテナンス用の書類の概要

上記の要約だけでは、疑問がどんどんと出てきます。
メンテナンス用の書類の概要

市販のRPGでも、「魔力」「賢さ」「精神」の数値が増えると、何に影響するかは、ゲームごとに違います。
メンテナンス用の書類の概要

つまり、
メンテナンス用の書類の概要

などのように、何によって決定されるのかを、書いてください。
メンテナンス用の書類の概要

もし要件定義書など別の書類に書いてあるなら、それを参照する形で簡略化してもいいですが、しかし要件定義書には一般に変数名(「attack_power」とか)は書かれていないので、やはり、こういうコード解説書も作っておくのが良いでしょう。
メンテナンス用の書類の概要

たとえ、コード解説書の記述が、他の書類と説明がいちぶ重複していても、かまわないでしょう。
メンテナンス用の書類の概要

むしろ、他の書類と相互に照合することにより、設計ミスなどを見つけやすくなる場合もあります。
メンテナンス用の書類の概要

とはいえ、コードのすべてを解説するのも時間的に困難なので、説明に優先順位をつけ、設計者に必要なことを優先して書くようにしましょう。
メンテナンス用の書類の概要

なお、このコード解説書を書く場合、けっして単に「どこの変数の内容がいつ、どういう内容に変わる」とかだけを書くのではなく、その作業を通して何を実現しようとしているのか等の意図も、書くようにしましょう。
メンテナンス用の書類の概要

自分の書くコード解説書でバグのある内容を記述してしまうというミスをしてしまう場合もあります。なので、万が一、そういうミスをしてしまった場合に、将来的に仕様書を読まされる後輩たちが修正しやすくするためにも、できれば各コードの意図・目的なども併記するようにしましょう。
メンテナンス用の書類の概要

たとえ執筆時点でバグは無くとも、ソフトウェアによっては将来的にOSやらミドルウェアやらの変更が必要になったりする場合もあり、そういう場合に既存の仕様では動作しなくなる場合もあるので、仕様に変更の必要が生じる場合もあります。
メンテナンス用の書類の概要

もちろん、細かいことはソースコードにコメント文で書け済みますが、しかしもしソース側でかけないような事があれば、解説書の側で書くと良いでしょう。
メンテナンス用の書類の概要

なので、そういった将来のミドルウェア変更のような事態も見越して、特に重要になりそうな各プログラムがあれば、そのプログラムの作業内容の意図・目的なども、できれば、どこかに書いておきましょう。
メンテナンス用の書類の概要

とにかく、それぞれの書類で説明が他書類と重複していて説明文がやや増えても、説明の多いぶんには、デバッグが効率化するので問題ないのです。仕様書の分野では、説明の「大は小を兼ねる」です。
メンテナンス用の書類の概要

後任者が、仕様書や「要件定義書」や「○○設計書」などの各種の書類などを読むのは、仕組みを把握したり完成目標を確認する理由のほかにも、前任者の開発の経緯やそれにともなう思考の経緯を知りたいという理由もあります。
メンテナンス用の書類の概要

たとえば、もし古いソフトに不具合が出たときなどに、設計ミスなので設計変更が必要ですが、 後任者がどこの設計部分がどういう事情でそういう設計になったかが分からないと、後任者がどう設計変更でイジレナイからです。
メンテナンス用の書類の概要

(実際には書類不足などで前任者の意図が分からない場合も多く、そのため、テストを頻繁に繰り返すことになり、工期が増えて残業なども増えてしまったりします。)なので、もしも書類がうまく残っていて、前任者の「こういう理由で、こういう設計にしました」という設計者の思考の経緯が書類に残っていれば便利です。というか、それが無いと困ります。しかし困ったことに、無い場合が多いので、日本の技術者はよく困ります。
メンテナンス用の書類の概要

設計者の思考の経緯を伝えられるような、そういう定型の書類形式というのが、ありません。「要件定義書」、各種の「○○仕様書」、「△△設計書」などを見ても、そこには通常、思考の経緯は書かれていません。
メンテナンス用の書類の概要

「要件定義書」や「○○設計書」などは無いよりかはマシで、思考の経緯などを推測するヒントにはなりますが、あくまでヒントどまりです。 「部品と機能の対応表」のようなものがあれば、かなりヒントにはなりますが、しかし、それでもヒントどまりです。
メンテナンス用の書類の概要

なお「部品と機能の対応表」の目的は、けっしてヒント目的だけでなく、設計内容のチェック用資料や他ソフトなどとの連携をする際の資料なども兼ねています。なので、たとえ思考の経緯を残した書類を書けても、「部品と機能の対応表」の種類も書類作成を省略せずに作るべきです。
メンテナンス用の書類の概要

とにかく、後任者のために書類を残すとき、思考の経緯もうまく手短かに分かるように書類も作りましょう。
メンテナンス用の書類の概要

このコード解説書のページ数は特には決まっていませんが、おおむね、持ち運びやすい程度の厚さになるページ数にしておくべきでしょう。
メンテナンス用の書類の概要

この手のメンテナス資料でよくあるトラブルが、退職エンジニアの資料紛失です。
メンテナンス用の書類の概要

会社の上司が、メンテナンス資料の定期チェックをサボりたいあまりに、担当エンジニア個々人のパソコンにだけ資料を保存させておいて、そのエンジニアが退職などしたときに資料が紛失するトラブルが日本各地で多発しています。(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない場合が多い。)退職したエンジニアの使っていたパソコンは、次の新人のためにフォーマット初期化するので、フォーマットの際にメンテナンス資料も消えてしまうというトラブルです。
メンテナンス用の書類の概要

「会社の共有フォルダにメンテ資料を置きましょう」と提案しようにも、しかし上司のチェックすらされてない資料が共有フォルダに置かれるわけもないので、結局はそういう会社ではエンジニア個人のパソコンでメンテ資料を管理させられたりもします。そして、いつしかメンテ資料が消失しています。
メンテナンス用の書類の概要

この手の資料消失のトラブルを未然防止する簡単な方法は、定期的に、部署の部長課長などや上司などの管理者が、現場エンジニアから上がってきたメンテナンス資料の原稿を、(管理者が)定期的にチェックする必要があります。
メンテナンス用の書類の概要

また、こうやって定期チェックすれば、万が一、メンテ資料消失しても、資料を普段から検査してきた上司や検査担当者の頭の中に記憶が残っているので、ノウハウの復旧が比較的に容易です。
メンテナンス用の書類の概要

しかし、部長や課長などが原稿チェックを面倒くさがっていると、上述のようなトラブルになります。
メンテナンス用の書類の概要

どこの技術系の企業でも、設計図のチェックは念入りに行いますが、しかしメンテナンス用資料のチェックが省略されたりする会社が多くあります。 資料紛失は会社側の自業自得でもあります。
メンテナンス用の書類の概要

なお、上司がチェックを面倒くさがっているという理由でメンテ資料が個人管理されている場合、当然、その資料は印刷などはされていません(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない)
メンテナンス用の書類の概要

なので、退職しなくても、ハードディスク故障などが起きればメンテ資料は消失して一巻の終わりです。
メンテナンス用の書類の概要

退職が決まったときに会社は引継ぎ資料をエンジニアに作成させようとしますが、当然、上述のような技術資料が急に作れるわけもなく、そもそも資料の内容が上司や同格の技術力のエンジニアから検証チェックもされてないので信頼性も不明だし、よって急ごしらえの資料作成は大抵、失敗に終わります。
メンテナンス用の書類の概要

根本的な原因は、メンテ資料のための作成費用を普段から出していなかった会社の態度です。また、この手の会社は、そもそも論として、退職エンジニアより昔の前任者からのメンテ資料すら用意していないのが通例です。そんな杜撰(ずさん)な管理体制なので、大抵の企業では、急ごしらえのメンテ資料の作成は失敗します。会社の自業自得です。
メンテナンス用の書類の概要

つまり資料消失であわてる会社というのは、そもそも、まともにメンテ資料の上司によるチェックもしていなかったという会社であり、いろいろと自業自得です。
「単位動作」という概念

主に機械工学教育の用語なのですが、「単位動作」という用語があります。
「単位動作」という概念

たとえば、熟練工の動作は、一見すると色んなスキルを習得しているので複雑に見えますが、しかし動作のひとつひとつは、たとえば卓上ボール盤なら教科書どおりの卓上ボール盤の使い方ですし、やすりがけ の動作も、教科書どおりの動作です。
「単位動作」という概念

複雑な動作も、教科書どおりの動作を、組み合わせただけに過ぎません。
「単位動作」という概念

そして、その やすりがけ だけの動作の説明も、図や写真などを使って、「手順1:○○をする。」、「手順2:△△をする。」などと一段階ずつ、1ステップも抜かりなく 教えます。
「単位動作」という概念

だから、工業高校や大学の機械工作実習では、教科書どおりの動作をひとつずつ、教えます。
「単位動作」という概念

けっして、いっぺんにまとめて、別種の動作を教えません。
「単位動作」という概念

このように、動作をひとつひとつの単純な動作に分解することを単位動作といいます。
「単位動作」という概念

なぜ、わざわざこんな事を説明するかというと、世間では複雑な物事を説明するときなのに、いっぺんに教えたがる人がいます。しかし、そういう教え方は、多くの開発現場ではNG(エヌジー、ノー・グッド)です。
「単位動作」という概念

残念なことに、インターネット上には、一見すると説明書の文章量が多くても、実態を読むと、このような作者以外でないと操作方法を読み解けないようなダメな説明法をされているツールも、残念ながらネットに多く公開されてしまっています。
「単位動作」という概念

単位動作を意識した解説の書き方は、べつに難しくなく、普通に、 たとえばwindowsのオフィスソフトなどのヘルプファイルや、あるいはオフィスソフトについての市販の操作解説書のように、 「~~をしたい」といった操作目的の種類ごとに一個ずつ手順を段階的に教えればよいだけです。
「単位動作」という概念

単位動作の説明を軽んじる人が根本的に勘違いしていることは、「複雑な動作を練習したほうが、スキルが上達する」という勘違いです。
「単位動作」という概念

むしろ物理学の公式のように、単純で短いものに置き換えたほうが、物事を考える際の部品として使いやすくなるのです。 だから実際の順序は、「単純な動作を見つけ出すために、その何倍もの練習や試作をする」のです。たとえるなら、発明家の努力のようなものです。「99%の努力の上での、1%のひらめき」です。
実社会のデータベースでは過去データは消さない

在庫管理ソフトで、もし在庫部品データで、購入元メーカーで生産中止になったりした部品があっても、一切、在庫データベースからは登録を消しません。
実社会のデータベースでは過去データは消さない

もし消したりすると、次の登録番号の部品との登録情報の連続性が無くなり、登録データが飛び飛びになるので、大変に管理が難しくなるからです。
実社会のデータベースでは過去データは消さない

だからともかく、生産中止部品のデータベース管理では普通、その部品の末尾コメントに「生産中止」などと書き足すだけにして、登録そのものは維持します。
実社会のデータベースでは過去データは消さない

また、自分が使っていなくても、過去の自社製品を購入した客先がその部品を組み込まれた自社製品を使っている場合もありますので、残す必要があります。
実社会のデータベースでは過去データは消さない

だからもし、生産中止でなく単に入力ミスなどで登録済みの部品をまた登録してしまったことが判明した場合も、 最新の登録IDでない限りは、消すのではなく、末尾コメントに「登録ミス。すでにID○番で登録済み。」のような記録を書いて残したままにするのです。
実社会のデータベースでは過去データは消さない

こういうのはデータベースを運用する際の基本テクニックです。
実社会のデータベースでは過去データは消さない

製造業の図面などの「部品表」の番号でも、同じようなテクニックが使われます。設計変更により過去の廃止になった部品に当てられていた番号は、消すのではなく、新規の番号を確保して、その新規番号に代替の新部品を割り当てるというテクニックです。
実社会のデータベースでは過去データは消さない

また、「登録IDを最整列して並び替える」なんてことは、一切、しません。そもそも、在庫ソフトにそのような機能も原則、ありません。
実社会のデータベースでは過去データは消さない

なぜなら、すでに紙に印刷した実物の台帳に保管されている登録ID番号までを、在庫管理ソフトで書き換えることは不可能だからです。
実社会のデータベースでは過去データは消さない

一般に在庫の台帳は小さな事業所でも数千種類の在庫部品があるので、台帳にあるその数千種の再チェックをするのは時間の無駄なので、並び替えはしません。もし在庫番号の並び替えをすると、「本当に並び替え後の番号が合っているか?」などのチェックの手間が生じます。
品質の検証

製造業でもIT企業でも品質の検証は、部品ごとの検証と、全体の組立てをしたあとの検証という、最低でも2段階です。
品質の検証

少なくとも、自動車業界はそうです。
品質の検証

個々の材料部品などは、実際に引張り試験や荷重試験などを実際に物理実験を行い、部品の耐久値が規定や要求仕様を満たしているかを、事前に確認します。そして自動車の走行試験や衝突試験などは、実際に部品を組み立てて製品の状態である自動車にしてから走らせて見るしか、方法はありません。
品質の検証

チェックにおいて、シミュレーションなどは無駄です。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もありません。
品質の検証

「チェックの最終確認においてシミュレーションが無駄」といのは、これは自動車業界だけでなく、航空宇宙などでも同様です。日本のJAXAは「はやぶさ」の部品モジュールの開発において、実際に部品を組み立てたうえでの(シミュレーションではなく)物理実験をしています(※ 講談社ブルーバックス『小惑星探査機「はやぶさ」の超技術』で確認できます。)。
品質の検証

また、産業技術総合研究所での測定の国家標準器開発などでも同様の手法であり、実際に測定器を製品として組み立てた上での物理実験をしています(テレビ番組では、TBS科学番組『夢の扉』でメタンハイドレート採掘の産総研の研究者が、そうシミュレーションの問題点を指摘しました)。
品質の検証

ソフトウェアの開発では原理的に物理実験は無理ですが、それでも不具合対策の確認は、最終的には、実際にそのソフトをユーザー視点で使用してみる「実践」/「試用」しかありません。
品質の検証

ソフトウェア業界だと、個々の部品ごとにチェックすることを「単体テスト」といいます。一方、全体的に組みたててみてチェックすることを「ビッグバンテスト」と言います。
品質の検証

さて、チェックにおいて、シミュレーションなどは無駄であり。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もないのでした。
品質の検証

ではシミュレーションの意義は何かと言うと、工業系に強いライター(「文筆家」の意味)の山根一眞『メタルカラー』シリーズのどれかに書かれていると思いますが、意義はけっして直接のチェックではなく、既に行った物理的な検証実験をもとにそれをシミュレーションと照らし合わせることにより相互検証することで、検証回数を減らすことにより費用節約するのが目的です。
品質の検証

たとえばシミュレーションなしでは20台の機械装置を耐久実験のため壊さないといけない工程であると仮定して、もしシミュレーションありなら耐久試験で壊すのは12台ですむ工程にできるなら、今後の自社の新製品では8台ぶんの費用が節約できます。そういうコストダウン投資のためにシミュレーションをするのです。
品質テスト

ソフトウェアのテストは、IT企業では、よく新人がやらされる仕事でもあります。新人研修に組み込まれていたり、研修明けによく与えられる仕事でもあります。
品質テスト

なぜなら、自社ソフトウェアの内部構造の知識が乏しくてもテスト自体は可能だからです。
品質テスト

製造業などでも、多品種少量生産の設備機械そのものの生産では、たとえば簡易的な耐久試験などのために「実機のボタンAを押した後に画面遷移後にボタンBを押すのを、50回繰り返す」みたいな簡易的かつ長めの時間の繰り返しテストは、よく新人の仕事です。(なお、50000回の繰り返しみたいにテストが長すぎると人間じゃ無理だし(機械で繰り返すことになる)製品が磨耗して壊れたり製品寿命が大幅に減るので、せいぜい人間でも可能な500回くらいまでにとどめて、人間がテストしたりします。)
品質テスト

どの業界でも、テストのうち、時間の掛かる繰り返し試験は、よく新人に与えられる仕事です。
品質テスト

いちおう、設備機械の組立て直後の段階で、「ボタンAを1回だけ押すテスト。ボタンBを1回だけ押すテスト。」みたいな(繰り返しでない)短時間テストは、機械を組み立てした生産者本人が現場で行います。しかし、「500回繰り返す」みたいな仕事は長いので、新人がテスターを行うのがよくある会社風景です。
オーバーエンジニアリングを避ける

「オーバーエンジニアリング」(over engineering)という用語があり、善かれと思ってもか、余計な設計をしてしまう事です。」
オーバーエンジニアリングを避ける

たとえばソフトウェアの設計の場合、あらゆるバグを想定して個別に対応したコードを書こうようとしてしまうと、コードが長大になってしまい、保守性がいちじるしく低下してしまいます。
オーバーエンジニアリングを避ける

システムのあらゆる部分にバックアップを持つのも、時間的にも費用的にも不可能であり、オーバーエンジニアリングです。
オーバーエンジニアリングを避ける

製品と寸分も違わぬデザインパターンを追求しようとして、ろくに実装もしないのもあります。また、そのような発想で書かれたマニュアルは、膨大な学習コストが必要であり、実用性が乏しいです。
オーバーエンジニアリングを避ける

最小限の機能だけのプロトタイプを作る手法です。
オーバーエンジニアリングを避ける

生命などの安全にかかわるものでもないかぎり、失敗を許容しましょう。
オーバーエンジニアリングを避ける

機能が実際に必要になるまで追加しない方法です。
オーバーエンジニアリングを避ける

ソフトウェアの場合、あとからでも比較的に容易に追加できることが多いので、こっちのほうが良いでしょう。
オーバーエンジニアリングを避ける

ただし、航空宇宙や造船などは別かもしれません。
工学では現状、「設計図とは何か?」といった理論は存在しません。情報工学でも、「IT企業の仕様書をどう書くか?」という書籍は、ほとんどありません。大学生向けの情報工学の参考書でも、まず触れられてない分野です。
本ページでは現状では参照していない文献ですが(2022年2月11日)、設計の理論を紹介していると思われる関連文献として『岩波講座 現代工学の基礎』があります。ある程度、設計についての抽象的な説明があるかもしれません(たとえば『岩波講座 現代工学の基礎〈1〉設計の方法論』(2000/5/10)あたり)。 しかし岩波のこの本はそんなに厚くないし、ソフトウェアも含めては説明していなかったかもしれません(手元にないので確認できません)。
ITの場合、ビルド手順の記録が必要

集団でソフトウェアを作るとき、そのソフトウェアのビルド方法を仕様書に書かないといけません。(これは製造業の設計図などには無い、IT業界の独自の事情です。)
ITの場合、ビルド手順の記録が必要

ビルドとは、実行ファイルを作ることです。
ITの場合、ビルド手順の記録が必要

Visual Studio などのソフトウェア開発環境ツールは大抵、ビルド機能もあるので、最低限、作者が実際に使用した開発ツールを書いておく必要があります。ビルドに必要としたソフトウェア(ビルド実行ソフトや、必要なライブラリ)、ビルドのためのコマンドや操作手順なども、ひとつひとつ詳細に書くべきです。
ITの場合、ビルド手順の記録が必要

実際に自分がそれらビルド手順のとおりにソフトウェアだけをインストールと設定を試してみて、もしその手順の指定に従えば(従うのが知識的に簡単かどうかはともかく)、とりあえずビルドできて、実行ファイルを生成できる程度には、書く必要があります。
ITの場合、ビルド手順の記録が必要

ソースコード公開サイトなどのプログラムを見ると、説明書を見てもどこにもビルド方法や実行環境が書かれておらず、ビルドできずに使いようのないコードが時々あります。ビルド不可能ではあまり有意義なソースとは言えないでしょう。
必要な書類

一般のIT業界や製造業の場合、集団作業で必要となる書類は、主に下記のセットでしょう(編集者Sの推測)。
必要な書類

設計図とは完成図のことです。
必要な書類

さて、一般のIT企業や製造業では上記の設計図~参考資料に加え、必要に応じて「説明書」、などを加える場合もあります(業界や会社によっては、説明書は上記セットとは別の本棚などに分離する場合もある)。この4〜5点セットの書類を、集団作業の便宜のために、将来にわたって残していきます。(土建や製造業などの堅い業界の場合は、「設計図書」(せっけい としょ)、などの名前で管理されることもあります)
必要な書類

娯楽産業ではない一般のIT企業や製造業でも、製品の企画に至った経緯を記した書類を、大元のアイデアを考えた会社の側では残しています。(ただし一般企業の場合、社内プレゼン用資料の流用の場合もある)。上記セット一覧のうちの「設計図」はゲーム業界では「仕様書」に対応しており、「企画に至った経緯を示した書類」は「企画書」に対応しています。一般企業では書類の名前は、「企画書」ではない場合も多く、業界や会社によって異なります。
必要な書類

企画書だけでなく、マトモな科学論文とかでも、既存品と今回の製品とはどう違うのかという構成が好まれます。つまり、論文なら「何を新発見したのか? → いままでの理論ではどうだったか?それと今回の新発見とでは何が違うか? → 発見のプロセスや詳細など」といった構成が、マトモな科学論文のあるべき構成です。
必要な書類

また、メンテナンスのための図面として、「フロー図」とか「モジュール図」や「システム図」等、設計図としての目的でない将来的なメンテナンス改修などを見越して作成される図を、保存しておく必要があります。
必要な書類

一般IT業界の仕様書の書き方の本やwebサイトを見ると、「要件定義書」「内部設計書」「外部設計書」「ネットワーク図」「業務フロー図」「インターフェース設計書」「モジュール設計書」などの色々な書類・図面がありますが、発注元で最低限必要なのは上記4点セット(完成予想図、メンテ用資料、企画書類、外部資料)でしょう。IT業界特有の設計書類も、完成予想図またはメンテ用資料を作成するため手段に過ぎません。
「設計図」とは完成図である

では「設計図」とは何かというと、製造業の場合での「設計図」の意味を説明すると、それは「完成予想図」です。「完成予想図」というところがポイントで、実は生産方法などは指定していないのです。なので設計図だけでは、実は何も生産できないのです。
「設計図」とは完成図である

なので設計図に加えて、現場で必要な生産方法の技術をもった技術者が、さらに必要です。なので、設計図はあくまで、最低限必要な情報でしかないのです。実際には、設計図以外にも、生産方法についてのさまざまな情報が必要です。
「設計図」とは完成図である

ですが、どこの業界でも、生産方法については図面化しないか、たとえノウハウを部分的に文書化していても社外秘にしていて非公表なのが通常です。
「設計図」とは完成図である

IT業界でも、あるソフト製品のプログラミングの具体的なノウハウについては、その製品の「仕様書」には記載されないのが通常です。
「設計図」とは完成図である

完成予想図として「部品図として、このような寸法(各部の長さ)・形状・材料をもった部品を図面の指定どおりに作れば、あとは組立図に部品どうしの相互位置が書いてあるので、(組立図の)その位置指定とおりに取り付ければ、必ず完成しますよ」
「設計図」とは完成図である

という状態にまで、部品図と組立図の状態をそれぞれ完成予想図の形で書き上げていくのが、図面を書くという事です。
「設計図」とは完成図である

技術的の企業でいう「設計図」の意味は、おおむね、こういう意味です。
「設計図」とは完成図である

もし、納品される品物が仕様を満たしてない場合、けっして合格品としてはいけず(つまり「検収」してはいけず)、(発注者は)協力会社に作り直しを要求します。この仕様違反のさいの作り直し要求はIT業界にかぎらず製造業でもどこでも、受け入れ検査は通常、そういう仕組みです。
「設計図」とは完成図である

ソフトウェアを作る場合も、最終的に製品の完成の段階では、最低限このような水準にまで、設計図を作りこんでいきましょう。(ただし、ソフトウェアには「寸法」など形状の条件は無いので、そこはアルゴリズム的な条件に意味を読み替えること。)
「設計図」とは完成図である

製造業では図面をもとに見積もりをします。基本的に技術系の業界では、設計図をもとに見積もりが行われるます。
「設計図」とは完成図である

学生は企業社会を知らないと思うので説明しますが、コンピュータ業界にかぎらず、そもそも製造業なども含む技術系の業界で、設計から生産までの流れがどういう工程で行われているか、説明します。
「設計図」とは完成図である

まず、なにかの設計図では、具体的な生産方法は指示しません。たとえば、組み立てた後の形状がどうなってるかは組立図(くみたてず)に描いても、しかし、「どうやれば組み立てられるか?」とかの情報は一切、そういう事については『設計図』では指示しません。
「設計図」とは完成図である

ともかく、なにかの設計図は通常、その製品の完成図である必要があります。製造業で「図面」と呼ばれているものは、こういった具体的な完成予想図のことです。
「設計図」とは完成図である

そして、その完成図はいくつもの部品から成り立っているのが普通なので、完成品をいくつかモジュールごとに分解した部品図(ぶひんず)をいくつも作成して、それぞれの作成担当の作業者に渡します。
「設計図」とは完成図である

こうすることで、分業もしやすくなり、一石二鳥です。
「設計図」とは完成図である

基本としては、設計図とは、設計図だけを見ても、あいまいさの無い状態で完成品の満たすべき具体的な条件が分かるようにしなければなりません。
「設計図」とは完成図である

さて、製造業などでも、「図面」という完成予想図があります。
「設計図」とは完成図である

よく、IT業界でいう「現場で見つかった仕様書の不具合を仕様書にフィードバックする」とか言う表現は、おそらく完成予想図のような書類のことを指していると思います。
「設計図」とは完成図である

なぜなら製造業でもフィードバックは図面に対して行います。なので、製造中に不具合が見つかれば、どんどんと図面が改訂されてゆくし、そのために設計者は現場に立ち会うし、場合によっては設計者みずからが製造もしていきます。
「設計図」とは完成図である

技術系の業界では一般に、書類で作業指示を出すときに、いちいち、けっして具体的に、「作業員であるアナタは、○○のコンピュータの△△ボタンを押して、××をしてください」のような指示は出さないです。
「設計図」とは完成図である

指示はそう出すのではなく、図面のような完成予想図(ただし決定稿)を出して、「この完成予想図のとおりになるように作っておいてください。」というような指示が出ます。
「設計図」とは完成図である

さて、IT業界の場合、末端の部品プログラム完成予想図を描く前に、普通の設計では既にフローチャート図または状態遷移図などといった、全体的なシステムの図面を書くのが望ましいとされています。(以降の説明では、言い回しの省略のため、フローチャート図または状態遷移図を単に『フロー図』または『フローチャート図』と略記する。)
「設計図」とは完成図である

なので、もし横断的な説明をしたければ、このフローチャート図を作るとき、このフローチャート側に説明を追加するとか、あるいは、フローチャート図を参照する形で別途の参考図を追加するとかすれば、良いかもしれません。
「設計図」とは完成図である

こうすれば、もし末端部品プログラムを訂正することになっても、訂正の必要のある図面は、末端プログラム図面と、その直接の上流のフロー図あるいはフロー別途参考図だけのたった2枚に限定できますので、訂正の手間を減らせるので効率的です。
「設計図」とは完成図である

なお、もしかしたらIT業界でも、状態遷移図やフローチャートを描かないで設計する事態も企業によっては横行しているかもしれませんが(原理的には、状態遷移図やフローチャート図が無くても、エクセルなどで作成した部品プログラム仕様とその組み立て仕様のエクセル形式の完成予想図だけでも、原理的にはソフト設計できてしまう)、しかし、こういう状態遷移図などの画像での説明を省いた設計では設計ミスが発生しやすく、結局、再設計などの手間が掛かってしまうのがオチです。
「設計図」とは完成図である

なお、一枚の仕様書の中では、内容の重複はオッケーです。
「設計図」とは完成図である

たとえば、機能の似たモノを2個つくるとき、
「設計図」とは完成図である

2個目の説明では、「○○については△△と同じ」のように、「~~~と同じ」というふうに説明できるから、です。製造業でも、一枚の図面に正面図と側面図の2方向の図のある場合、側面図に参照値として正面図の値を書くと、正面図の設計変更にともない、ときどき側面図にある参照値を修正し忘れるミスがあります。)
「設計図」とは完成図である

なので、よほど仕組みの複雑な難しい製品でないかぎり、なるべく2回目以降の説明では具体的内容は書かないのでおくのが、設計の図面では修正モレを防げるので安全です。
「設計図」とは完成図である

ただし、これはあくまで、設計図面の書き方です。教本や指導書などの書き方とは、設計図面の書き方は、違います。もし、新人むけの指導書や教科書・教本を書く場合には、やや重複のある内容でも何度も説明して覚えさせましょう。
要求事項書

要求事項は、「○○してもらいたい」という指定も必要ですが、ソレとは別に、できれば、「なんの目的で、そういう指定をしているか?」などの理由も書いてあると、ニュアンスが正確に伝わるので、伝達ミスなども減ります。
要求事項書

企業秘密などで無いかぎり、できるだけ、目的も平気したほうが良いでしょう。
要求事項書

要求事項の書類には、要求には理由も併記するのが望ましいと指導されているようです。
要求事項書

さて、一般IT企業で要求事項書の話題に戻るとして、また、意外と伝達側が設計ミスをする場合もあるので、目的も書面で伝えておくことにより、相手先の人が、気を聞かして検証してくれます(べつにボランティアで検証してくれるわけではなく、どっちみち相手先が設計中に結果的に検証することになるで、だったら要求事項に目的も書いておいたほうが効率的になる)。
要求事項書

なんども指摘するが、「要求事項」だの「設計図」だの何種類も作る書類セットの書き方では、説明が重なって多いぶんには問題ないのです。(ただし、要点などを抜き出した簡略版の説明も必要。)
要求事項書

大は小を兼ねます。
要求事項書

なお、社会人の情報伝達では、結論を先に言うのがマナーなので(詳しくは『中学校国語/現代文/報告書の書き方』)、要求を先に伝えてから、理由を直後に伝えます。つまり、文章のテンプレートとしては、
要求事項書

のような順番になります。
要求事項書

設計図の各書類は一般的に外部には非公開なので、書類セットくらいでしか体系的な説明をできないので、むしろ別書類にて説明の重複などがあって相互検証できるくらいのほうが、安全なのです。なお、要求事項の段階では、あまり細かく事項書を作りすぎずに、そのぶん実際のプログラムの開発を早めましょう。
データ台帳

重要なことは、一般のソフトウェア開発などでの実務では、なんらかの特殊な数値データが組み込まれている場合、台帳と実物プログラムとによってダブルチェックをするという事です。(ゲームだけでなく、製造業の組み込みソフト開発などでも、台帳などによってダブルチェックをしています。)
データ台帳

IT業界では、ダブルチェックを軽視している人が多いですが(たとえば電卓とパソコンソフトとの計算結果のダブルチェックを批判する言説がネットに多い)、そういうのは製造業や組み込み業界などでの実務を知らない知ったかぶりのタワゴトなので無視しましょう。
データ台帳

マトモな業界では、プログラムの検証のため、そのソフト以外およびそのソフトを動かしているハードウェアとは別のデバイス(電卓でも良い)を使って、ダブルチェックをするのが常識です。(※この常識には出典を出せませんが(企業秘密などに関わるので)、しかしダブルチェックを軽視する側の主張も満足な出典を出せていないので、対抗的にこの文を残します。)
データ台帳

さて、入力されたハズのデータの台帳のような内容の一覧の書類が、一般の技術系企業では必要です。業界で「台帳」と言うのかは知りません。名前が無いと困るので、とりあえず土木工学ではこういうのを「○○台帳」というので、それに習って「データ台帳」という題名を本セクションでは、つけているだけです。なので、IT企業では別の呼び名かもしれません。
多項式近似

測定値などで、入力変数が一変数なら、エクセルなどを用いて多項式近似が出来ます。
多項式近似

一般にIT業界での実務の多項式近似では、原理的には9次でも20次でも、どんなに次数が高くても(おそらく int 整数型の限界くらいまで)計算できてしまいますが、
多項式近似

しかしIT業界などの実務では人間の検算などの手間を減らすために、なるべく、せいぜい2次式や3次式といった、低めの次数におさえて利用するのが、IT企業では普通です。
多項式近似

もし先端科学のための多項式近似なら、9次を超えるような多項式近似をするような場合もありますが、しかし、一般の企業では、そこまでの多項式近似は不要ですし、むしろ検算などの管理の手間が増えるので、9次のような多すぎる次数は嫌われますので、なるべく2次ていどに抑えましょう。
バグあると人の死ぬ業界

ゲームではバグがあっても、人は死にません(過労自殺などを除けば)。なので、アイデアが思いついたら、どんどんとプロトタイプで試してみましょう。
バグあると人の死ぬ業界

ですが、他の業界だと、バグがあると人が死ぬ場合もあります。たとえば、製造業での、組み込み機器などがそうです。
バグあると人の死ぬ業界

書籍で紹介されている事例だと『メタルカラーの時代』シリーズ(山根一眞(やまね かずま)による取材)で、 「日本ユニシス」というIT企業がかつて、提携している別企業のNC工作機械に向けた組み込みソフトの開発で(組み込みソフト部分をユニシスが開発)、開発テスト中のバグにより工作機械の刃物が本体にぶつかって折れて飛んできて、あやうく人が死ぬところだった、 ・・・という感じの事例がインタビュー先のプログラマから紹介されています。 それまで日本ユニシスおよびその担当プログラマーでは、組み込みの仕事はほとんど扱わずに、どちらかというとIT業界内での顧客を仕事をしていたので、そういう人が死にそうな事例に経験することがなかったので、製造業の組み込みソフトでは特にバグおよびバグ予防に対する考えをIT業界内の仕事とは変えなければならない必要があることに気づかされた、とユニシスの技術者はインタビューで述懐しています。
履歴の管理

一般のIT企業でいう仕事の「仕様書」では、開発前の段階で書いた要件定義書や設計図(完成予想図)やコード解説書など」を、ソフト完成後にも残す必要があります。
履歴の管理

なぜなら、開発前~開発中の経緯を、上司や他部署に事後的に報告したり、のちに入社してくる後輩などに教育としてソフト開発時の出来事を教えるためです。
履歴の管理

このため、こういった仕事の書類には、著者や、著作・改訂の日時(「改訂日: 2018年8月30日」)や改訂者(「改訂者: 山田太郎」)などの履歴(りれき)も記載する必要もあります。
履歴の管理

のようになります。(企業では、こういうページのパソコンでの文書管理は、エクセルなどの表形式データになってるのが普通。)
履歴の管理

さらに改訂の際には、それぞれの版の改訂内容の要約を書く必要すら、あります。
履歴の管理

アマチュアの場合なら、『メモ帳』アプリなどで説明する場合もあるかもしれないので、たとえば
履歴の管理

のようにアレンジする必要があるかもしれません。
履歴の管理

アマチュアのゲーム製作の場合、エクセルまでは不要でしょう。
ファイル名の冒頭番号

ゲームを例に説明します。
ファイル名の冒頭番号

ゲーム産業に限ったことではないのですが、企業でのパソコン内での、ファイル名やフォルダ名の管理手法として、たとえば何かの説明書きのファイルがいくつもある場合、
ファイル名の冒頭番号

などのように番号順をつけて命名することもあります。「01_キャラクター設定」でひとつのフォルダ名です。なぜこのように番号を冒頭につけるかというと、もしパソコン上で名前順に並び替えたときに、必ず狙った順番どおりにさせるためです。
ファイル名の冒頭番号

そして、たとえば「キャラクター設定」フォルダ内に、さらに
ファイル名の冒頭番号

のように、さらに 番号づけの設定があることもあります。
ファイル名の冒頭番号

たとえば、「ゴンザレス」というキャラが主人公のゲームの場合、彼が最初に来てもらわないと困るわけです。もし番号が冒頭に無いと、「ゴンザレス」よりも「アルベルト」のほうが五十音順では先に来てしまいます。
ファイル名の冒頭番号

しかし、上記のように番号を冒頭につける方式を採用することで、あとでどんな名前の新キャラクターを追加しようが、必ずファイル検索の名前順検索では「ゴンザレス」が最初に来るようになるのです。
ファイル名の冒頭番号

なお、業務用のファイルでは一般的に、冒頭番号と項目名とが別々のものであることを強調するために、半角スペースを使わずにアンダーバー「_」を使うのが一般的です。
ファイル名の冒頭番号

IT企業に限らず製造業でも、たとえば図面ファイルでは
ファイル名の冒頭番号

などと、冒頭番号ごと名前をつけてフォルダ管理するのが一般的です。
ファイル名の冒頭番号

フリーソフトのファイル構成などでも、本ページはゲーム教科書なのでゲームに置き換えて説明しますが、
ファイル名の冒頭番号

のようなファイル構成のフリーソフトも時々、見かけます。
説明書

フリーゲームなどは、あまり説明書が細かくかかれないので、気にする必要はないでしょうが、一般IT企業のソフトウェア説明書や製造業の組み込みソフトなどは、もっと細かく一通りの操作方法を説明します。
説明書

イメージしやすさの都合で本ページでは、製造業などの組み込みソフトを例に、説明書の書き方を説明します。
説明書

なんと、組み込みソフトの説明書を書くためには、操作テストが必要です。
説明書

だから例えば工場の生産ライン用の設備に組み込まれてる組み込みソフトの説明書なら、その説明書の文面は、工場で下書きしてるわけです。
説明書

オフィスで下書きするのではなく、工場で下書きするのです。なので、工場にノートブック(文房具)と筆記用具(要・赤ペン)を持ち込んで、そこで説明書の文面を下書きするわけです。
説明書

たいていの新人は、実機での操作テストに気が引けがちです。
説明書

実機で操作テストばかりしてると「周囲の先輩から『この新人は書類も読まずに実機をいじって遊んでる』と周囲に見られるんじゃないか?」と不安になったりとかして、実機によるテストを遠慮しがちです。また、仕様書は読んでて勉強になりますので、ついつい仕様書ばかり読みがちで、テストを遠慮しがちです。
説明書

しかし、それは新人特有のよくある勘違いなのです。説明書を書く場合にも、実機でテストプレイをするべきなのです。
説明書

なので、下書きが終わったら、さっさと実機テストをするべきなのです。
説明書

まず、仕様書などをもとに、説明書の大まかな章や節などの構成を、仮決めします。
説明書

大まかなページ数などの仮決めのために、仕方なく仕様書を見ながら、仕様書から想定されるハズの操作方法を書きます。
説明書

この下書きは、これはこれで必要であり、あとの操作テスト時にチェックすべき項目を示したチェックリスト的な意味合いもあるので、とりあえず、実機プレイなしですが下書きをします。
説明書

ですが、この想定した操作方法は、まだ何のテストもしてないので、高確率でミスが含まれています。
説明書

なので、下書きした説明書のプロトタイプと筆記用具(赤ペン)を持ちながら、実機のある現場に移動して、到着したら実機で説明書どおりにテストプレイしながら(絶対に説明書を見ながら、杓子定規に説明書どおりにプレイします)、実機操作中に発見した説明書のミスを、赤ペンで下書き説明書に、追記でメモ書きしていくワケです。
説明書

このように仕様書ばかり読んでないで、さっさとテストします。
説明書

だから、説明書を書くオフィスは、そういうテストが気軽にできる環境の近くに存在する必要があります。
説明書

また、組み込みソフトの説明書を書く技術者は、工場の組み込みソフトを書くなら、技術書の服装としてはブルーカラーの作業着で仕事してるわけです(背広ではないです)。作業着でないと原則、現場に入れないので
説明書

組み込みソフトは、機械などに組み込まれてるわけですから、安全が確保されていて可能な限り、仮想化などではなく、実機でテストします。 (仮想化でテストすると二度手間になります。なので可能なら最初から実機でテストしたほうが早いです。)
説明書

このような仕事を、よく新人がやらされます。
説明書

新人は消費者目線に近いので、どこの業界でも、新人がよくテスターにさせられることが多いのです。
説明書

同様の理由(消費者目線)で、説明書を書く仕事も、どこの業界でも、新人がよく説明書を書かされます。
説明書

子供向けの玩具で電子玩具の説明書などだと、場合によっては説明書の文面が子供口調(「~だよっ!」とか「~だね!」みたいな口調)で説明が書かれていたりしますが、けっして説明書を書くお仕事が子供の学校の図工みたいな作り方をしてるワケではないでしょうし、おそらくは実際の執筆手順は上記の組み込みソフトの説明書のような感じの手順で説明書を書いていってると思われます。説明書の口調という表面にダマされないようにしましょう。
説明書

ああいう子供口調やら女口調の説明書は、集団作業の場合なら、下書きの段階での口調は、普通のビジネスマン的な書類の口調で書いているか、たとえ くだけた下書きの場合でも普通の大人のくだけた口調で下書きを書いているのであって、あとの工程で口調だけ入れ替えて子供口調や女口調に入れ替えるという手間を掛けていると思われます。けっしてイキナリ、子供口調とかで書類を書きはじめるわけではありません。
パラメータ調整の理論

たとえば機械設計の業界で昔から言われている教訓として(なるべく新規設計では)「材料と構造を同時に変えるな」というのがあり、日経クロステックのwebサイトでもそう紹介されています。引用元の日経クロステックの記事では「2つ以上のものを同時に変更するときは、組み合わせによる問題が起こりやすいことを示唆している」と指摘されています。
メンテナンス用の書類の概要

完成形をつくるだけの「設計図」的な「仕様書」だけでは、バグ発生時や設計ミス発生時などのさいの修理が不可能です。
メンテナンス用の書類の概要

また、ITソフトウェアなら、移植などの際に、もしソースコードだけしかなくて書類不足だと、「コードがどのように動いているのか?」を後任の人が把握できずに、移植困難になってしまうトラブルもあります。
メンテナンス用の書類の概要

前任者が会社を辞めてしまっている場合などもあるので、色々と書類が必要でしょう。こういうことから、もし下記のような資料が無いと、不具合の発生時に、修理のための設計変更で、どこをどうイジればいいか特定できず、困ります。
メンテナンス用の書類の概要

というか、残念ながらこういう資料の不足している職場は多く、なので日本のIT技術者は困っています。
メンテナンス用の書類の概要

上記書類のうち、特に「部品と機能の対応表」、「コード解説書」は、メンテナンス目的以外にも、設計図のチェックにも利用される。なので、そういう目的もあるので、ぜひ作成しておくのが望ましい。
メンテナンス用の書類の概要

「部品と機能の対応表」のことを、IT業界で何と言うのか、このページの著者は知りません。しかし、ともかくそういう対応表がないと、メンテナンスが後々に困難になります。
メンテナンス用の書類の概要

発売後の(一般のIT企業では)ソフトにも、修理・メンテナンスが不可能になる場合があります。
メンテナンス用の書類の概要

そのため、製造業などの組み込みソフトなど、まともなIT業務では、ソースコードの内部構造・全体構造のコード解説書とでも言うべき書類があることが望ましいです。(特に名前は決まっていない。また、中小企業などでは作成しない場合もある)
メンテナンス用の書類の概要

一般のIT企業では「内部設計書」や「プログラム設計書」などの名前の場合もありますが、しかし既に設計図などで大まかな指定はできていますので、設計の時点では、これらの「設計書」が不要な場合も多くあります。
メンテナンス用の書類の概要

これらの書類の目的は、どちらかというと、設計よりも、後日に読み返したときのメモ書きです。主要な変数、主要な関数などは、第三者が、なんのドキュメントも無い状態でその意図を読み取るのは、なかなか手間が掛かります。なお、最終製品やあるいはコードだけから逆に設計書や設計図などを書き起こすことを「リバース・エンジニアリング」と言います。リバース・エンジニアリングは、本来なら、後任者などには、させるべきではないのです。
メンテナンス用の書類の概要

大目的として、完成後のメンテナンスなどの際に、リバース・エンジニアリングという手間のとても掛かる作業を、けっして後任者にしないでも済むように書類を残すのが、正しい書類作成および書類管理のありかたです。これが、前提の大目的です。これさえ押さえてくれれば、ほぼこのページで言いたいことは尽くされています。このページの残りの説明は、単にイメージを具体化するためのケーススタディです。
メンテナンス用の書類の概要

会社でリバース・エンジニアリングの手間の発生が起きるのは、経営者にとっても時間と予算のロスでしょう。また、リバース・エンジニアリングをさせられる側である社員も、利益を生み出すわけではない作業に時間を多く取られ、とても負担です。なのでとにかく、リバース・エンジニアリングの発生予防が必要です。
メンテナンス用の書類の概要

で、具体的にどうすればいいかというと、リバース・エンジニアリングの発生を防ぐためには、なんらかの方法で、少なくとも主要な変数や関数と、その設計意図の対応表のようなものが必要です。
メンテナンス用の書類の概要

(完成図である)設計図だけでは、このような機能の解説をするのは不可能または困難なので、さらに変数・関数と、設計意図との、対応表のようなものが必要です。この対応表のようなもののことを本wikiでは「コード解説書」と呼んでいます(IT業界で何と言うのか知りません)。(設計図だけでも機能の解説を出来ているなら、その部分は解説書に書く必要はありません。)
メンテナンス用の書類の概要

要するに、機能と部品との対応表も残すべきだという亊です。「この部品、どの機能に対応してるの?」ってのが分かればいいのです。
メンテナンス用の書類の概要

異業種の例ですが、下記の2つの回路の図面を見比べてください。
メンテナンス用の書類の概要

どう比べても、右の「フロー図」のほうが、仕組みが分かりやすいでしょう。もし回路設計の専門外の素人が上記の回路図面を見ても、フロー図のほうなら機能が一目瞭然です。
メンテナンス用の書類の概要

このように、部品と機能を比べる書類があれば、とても後任者がラクになります。
メンテナンス用の書類の概要

また、このような部品と機能の対応の書類を作っておくことで、設計ミスの防止にもつながります。
メンテナンス用の書類の概要

上記の図面の例は、電気回路の設計の業界のハナシなので、ITではないですが、ともかく、こういう部品と機能の対応表があると、仕事がいいカンジです。
メンテナンス用の書類の概要

「フロー図」だの「コード解説書」などの名前はどうでもいいです。重要なのは、部品と機能の対応表を残しておけ、という事です。
メンテナンス用の書類の概要

逆に言うと、部品と機能の対応が分からないような書類ばかりを作っていても、無駄です。
メンテナンス用の書類の概要

けっして、やみくもに「○○設計書」のような名前の書類をいくつも残すのではないべきです。目的である、「部品と機能の対応表」を忘れないようにしましょう。
メンテナンス用の書類の概要

IT業界でこういう書類を残しているか知りませんが、少なくとも電子回路の業界では、こういう書類を残しています。けっして、(ブラック企業だらけだと悪評高い)日本IT企業の習慣のマネではなく、世界に冠たる競争力をもつ日本のB to Bの電子機器の製造業の手法をマネしましょう。
メンテナンス用の書類の概要

一般の企業でのITソフトは、発売後から10年後や20年後にもメンテナンス等が必要な場合があるので、コードの全体構造の解説書が必要なのです。たかが1~2年で流行の廃れるソフトの管理手法なんか、手本にしてはいけません。
メンテナンス用の書類の概要

コード解説書を書かない場合、それでも将来的なリバースエンジニアリング予防のために解説を残したい場合には、おそらくですが、代わりに「仕様書」などの既存の種類に流用で、変数名や関数などの指定を記載したりする必要が生じるかもしれません。ソフトウェアの設計図(完成予想図)はその性質上、解説などはあまり長く書けません。それはそれで一つの方法です。勤務先などに応じて、うまく方法を選んでください。
メンテナンス用の書類の概要

しかし、個人製作ソフトの場合、仕様書は無いのが普通なので、簡易的にコード解説書を書いたほうが早いかもしれません。プログラミングは、仕事や学業などの都合で中断される場合もありますが、再開後に、中断前のアイデアなどを思い出すためにも、コード解説書は書かれていると便利です。(コレがないと、時間が経つと、ほぼ作業内容を忘れる。)
メンテナンス用の書類の概要

さて、経団連企業などの東証一部の上場企業のIT業界の人が「仕様書を書かないと、あとでコードの仕組みを忘れる」とか言ってるのは、きっと、このコード解説書のことでしょう。経団連発言の時代的な文脈的に、けっして要件定義書とか完成予想図とかのことではないハズなので、勘違いしないようにしましょう。
メンテナンス用の書類の概要

このコード解説書の書き方には、けっして、決まった書き方がありません(なので、市販の入門書では、紹介されてない)。ですが、ともかく、経団連企業とかの技術系企業の設計部門では、こういう書類も書くのが望ましいとされています。
メンテナンス用の書類の概要

重要なことは、コードのどの部分が、ソフトウェアのどのような機能を実現するために、何を構成しているかと言った情報を、コード解説書または仕様書などで残すことです。
メンテナンス用の書類の概要

システム構造を解説するには、要するに変数名や関数名や、モジュールが、設計図に示した設計意図にどう対応しているかを、記載できれば良いのです。こういった大目的をまず忘れないようにしましょう。
メンテナンス用の書類の概要

では、どうやったら、こういう解説をできるのかを、これから考えていきましょう。
メンテナンス用の書類の概要

ソフトウェア開発前には実際のシステム構造(プログラムをどういう仕組みにしたとか、変数名をどうつけたか、とか)を書くのが難しいので、ある程度、開発が進んでから、開発中にシステム構造を書くことになります。
メンテナンス用の書類の概要

このコード解説書には、決まった描き方がありません。(なので、一般むけの「仕様書の書き方」入門書では、紹介されていない。)
メンテナンス用の書類の概要

なお、この「コード解説書」書類の呼び名は特に決まっていません。呼び名が無いと不便なので、とりあえず「コード解説書」と呼ぶことにします。
メンテナンス用の書類の概要

まず、ソフトウェアのシステム構造を解説する場合、どのファイルがエントリポイント(コンパイル時に最初に呼び出されるファイル。Main関数などがある)なのか、そういうことから、コード解説書に書いてください。
メンテナンス用の書類の概要

C言語にはファイル分割という機能があり、ソースファイルを複数のファイルに分割できますので、実際のソフトウェアではファイルが何種類もできます。
メンテナンス用の書類の概要

なので、コード解説書にエントリポイントがどのファイルなのかを書いてないと、いちいち読者がファイルを開いて読まないと、どのファイルが最初に呼び出されるのかを理解できません。
メンテナンス用の書類の概要

ファイル分割されたファイルが幾つも(いくつも)ある場合、例えばゲームソフトだとして、ジャンルがRPGなら
メンテナンス用の書類の概要

などのようにファイルが幾つもある場合、
メンテナンス用の書類の概要

システム構造書に、
メンテナンス用の書類の概要

などのように、それらのファイルが何を処理しているのかを第三者が分かるように書いてください。また、なるべく箇条書きで書くのが、読みやすくて便利でしょう。
メンテナンス用の書類の概要

当たり前に残すべきメモのように思えるかもしれませんが、しかしこういったメモが残されてない職場は多くあります。悪い見本です。とにかく、瑣末なことでリバース・エンジニアリングを後任者にさせないように書類を残す習慣をつけましょう。
メンテナンス用の書類の概要

ダメな一般IT企業だと本当によくあるパターンで、ファイル解説の書類など何も残ってないのに自社アプリのファイルサーバーには「system.cpp」などの漠然とした名前のファイルだけがいくつもある場合が時々よくあり、「systemって何のシステムだよ・・・」と後任者があきれたくなるファイル名のプログラムがいくつもある場合、これは大変にリバース・エンジニアリングの手間を発生させる、プログラマーにとってイヤなパターンです。
メンテナンス用の書類の概要

暗黙の前提ですが、画面名やファイル名などの名前を決める際には、具体的な名前をつけるべきです。
メンテナンス用の書類の概要

書籍『ゲームプランナー入門 アイデア・企画書・仕様書の技術から就職まで』によると、ゲーム業界でもそう指導されています。
メンテナンス用の書類の概要

ゲーム業界に限らず、一般のIT業界でも同様に具体的に命名するべきでしょう。つまり、「file1.cpp」とか「a.cpp」みたいなファイル名は厳禁です。また変数名でも「b」とか「variable1」(英語でvariableとは「変数」という意味)みたいな変数名は避けてもらいたいです。
メンテナンス用の書類の概要

なお、一般企業では箇条書きの説明をするとき、よくエクセルなどの表形式で説明することもあります。
メンテナンス用の書類の概要

のような表形式でよく箇条書きが書かれます。
メンテナンス用の書類の概要

開発した原作者には、「ファイル名から予想がつくだろ?」と当然に思うことであっても、意外と、通じない場合がありますので、きちんとコード解説書に、ファイルの処理内容を文章で書くべきです。
メンテナンス用の書類の概要

例えば、RPGの「メニュー」と言われても、あなたは「道具」「装備」などの画面を思い浮かべても、ほかの人は、戦闘シーンの「戦う」「逃げる」などのコマンド画面を思い浮かべるかもしれませんし、あるいは会話イベントの「はい」「いいえ」などの返事の選択画面を思い浮かべるかもしれません。
メンテナンス用の書類の概要

また、「マップ」 map と言われても、あなたは「主人公が現在いる場所の周囲」を思い浮かべても、ほかの人は、道具「地図」を使うと画面表示される世界マップと、世界地図のなかでの、主人公のいる地方の位置を思い浮かべるかもしれません。
メンテナンス用の書類の概要

または、「洞窟などのダンジョンの構造が書かれた地図のような道具が、そのゲームの中にあるのでは?」とか想像する人もいます。
メンテナンス用の書類の概要

このほか、数学用語で「map」(日本語でいう写像(しゃぞう)のこと)という用語がありますので、それと混同される場合もあります。
メンテナンス用の書類の概要

このように、ファイル名だけだと、いろいろと想像されてしまいます。
メンテナンス用の書類の概要

なのでコード解説書を作る場合、もし仕様書側に解説が無い項目なら、そのファイルのソースコードを読まなくても理解できるように、きちんとファイル内容の要約を解説書に書きましょう。
メンテナンス用の書類の概要

このほか、どうしても「System.cpp」とかのような漠然とした名前のファイルがある場合、何のシステムなのか、わかるように書いてください。(そもそも、そういう漠然とした名前を避けたほう安全ですが。)
メンテナンス用の書類の概要

たとえばRPGを作るなら、
メンテナンス用の書類の概要

などのように、そのゲームで使うパラメーターについて、ひととおり、変数名と、その内容の要約を書いてください。
メンテナンス用の書類の概要

たとえ原作者には「当然だろ」と思えることであっても、他人には意外と通じません。
メンテナンス用の書類の概要

たとえば、「defence_power」と言われても、仮にアナタは「防御力」のことだと思っても、ある人は
メンテナンス用の書類の概要

とか、思うかもしれません。
メンテナンス用の書類の概要

また、防具の防御力と、人物の防御力とを、同じ変数にするか、違う変数にするのかどうかも、「defence_power」という名前だけでは分かりません。
メンテナンス用の書類の概要

でも「人物の防御力」というように要約があれば、「あっ、防具の防御力は、人物の防御力とは別の変数なんだな!」って分かります。
メンテナンス用の書類の概要

また、
メンテナンス用の書類の概要

のような、魔法のような非現実的なファンタジーを前提にしたパラメーターがある場合、そのパラメータが何に影響をするのか、仕様書のほかの部分に書いてください。
メンテナンス用の書類の概要

例えば、
メンテナンス用の書類の概要

上記の要約だけでは、疑問がどんどんと出てきます。
メンテナンス用の書類の概要

市販のRPGでも、「魔力」「賢さ」「精神」の数値が増えると、何に影響するかは、ゲームごとに違います。
メンテナンス用の書類の概要

つまり、
メンテナンス用の書類の概要

などのように、何によって決定されるのかを、書いてください。
メンテナンス用の書類の概要

もし要件定義書など別の書類に書いてあるなら、それを参照する形で簡略化してもいいですが、しかし要件定義書には一般に変数名(「attack_power」とか)は書かれていないので、やはり、こういうコード解説書も作っておくのが良いでしょう。
メンテナンス用の書類の概要

たとえ、コード解説書の記述が、他の書類と説明がいちぶ重複していても、かまわないでしょう。
メンテナンス用の書類の概要

むしろ、他の書類と相互に照合することにより、設計ミスなどを見つけやすくなる場合もあります。
メンテナンス用の書類の概要

とはいえ、コードのすべてを解説するのも時間的に困難なので、説明に優先順位をつけ、設計者に必要なことを優先して書くようにしましょう。
メンテナンス用の書類の概要

なお、このコード解説書を書く場合、けっして単に「どこの変数の内容がいつ、どういう内容に変わる」とかだけを書くのではなく、その作業を通して何を実現しようとしているのか等の意図も、書くようにしましょう。
メンテナンス用の書類の概要

自分の書くコード解説書でバグのある内容を記述してしまうというミスをしてしまう場合もあります。なので、万が一、そういうミスをしてしまった場合に、将来的に仕様書を読まされる後輩たちが修正しやすくするためにも、できれば各コードの意図・目的なども併記するようにしましょう。
メンテナンス用の書類の概要

たとえ執筆時点でバグは無くとも、ソフトウェアによっては将来的にOSやらミドルウェアやらの変更が必要になったりする場合もあり、そういう場合に既存の仕様では動作しなくなる場合もあるので、仕様に変更の必要が生じる場合もあります。
メンテナンス用の書類の概要

もちろん、細かいことはソースコードにコメント文で書け済みますが、しかしもしソース側でかけないような事があれば、解説書の側で書くと良いでしょう。
メンテナンス用の書類の概要

なので、そういった将来のミドルウェア変更のような事態も見越して、特に重要になりそうな各プログラムがあれば、そのプログラムの作業内容の意図・目的なども、できれば、どこかに書いておきましょう。
メンテナンス用の書類の概要

とにかく、それぞれの書類で説明が他書類と重複していて説明文がやや増えても、説明の多いぶんには、デバッグが効率化するので問題ないのです。仕様書の分野では、説明の「大は小を兼ねる」です。
メンテナンス用の書類の概要

後任者が、仕様書や「要件定義書」や「○○設計書」などの各種の書類などを読むのは、仕組みを把握したり完成目標を確認する理由のほかにも、前任者の開発の経緯やそれにともなう思考の経緯を知りたいという理由もあります。
メンテナンス用の書類の概要

たとえば、もし古いソフトに不具合が出たときなどに、設計ミスなので設計変更が必要ですが、 後任者がどこの設計部分がどういう事情でそういう設計になったかが分からないと、後任者がどう設計変更でイジレナイからです。
メンテナンス用の書類の概要

(実際には書類不足などで前任者の意図が分からない場合も多く、そのため、テストを頻繁に繰り返すことになり、工期が増えて残業なども増えてしまったりします。)なので、もしも書類がうまく残っていて、前任者の「こういう理由で、こういう設計にしました」という設計者の思考の経緯が書類に残っていれば便利です。というか、それが無いと困ります。しかし困ったことに、無い場合が多いので、日本の技術者はよく困ります。
メンテナンス用の書類の概要

設計者の思考の経緯を伝えられるような、そういう定型の書類形式というのが、ありません。「要件定義書」、各種の「○○仕様書」、「△△設計書」などを見ても、そこには通常、思考の経緯は書かれていません。
メンテナンス用の書類の概要

「要件定義書」や「○○設計書」などは無いよりかはマシで、思考の経緯などを推測するヒントにはなりますが、あくまでヒントどまりです。 「部品と機能の対応表」のようなものがあれば、かなりヒントにはなりますが、しかし、それでもヒントどまりです。
メンテナンス用の書類の概要

なお「部品と機能の対応表」の目的は、けっしてヒント目的だけでなく、設計内容のチェック用資料や他ソフトなどとの連携をする際の資料なども兼ねています。なので、たとえ思考の経緯を残した書類を書けても、「部品と機能の対応表」の種類も書類作成を省略せずに作るべきです。
メンテナンス用の書類の概要

とにかく、後任者のために書類を残すとき、思考の経緯もうまく手短かに分かるように書類も作りましょう。
メンテナンス用の書類の概要

このコード解説書のページ数は特には決まっていませんが、おおむね、持ち運びやすい程度の厚さになるページ数にしておくべきでしょう。
メンテナンス用の書類の概要

この手のメンテナス資料でよくあるトラブルが、退職エンジニアの資料紛失です。
メンテナンス用の書類の概要

会社の上司が、メンテナンス資料の定期チェックをサボりたいあまりに、担当エンジニア個々人のパソコンにだけ資料を保存させておいて、そのエンジニアが退職などしたときに資料が紛失するトラブルが日本各地で多発しています。(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない場合が多い。)退職したエンジニアの使っていたパソコンは、次の新人のためにフォーマット初期化するので、フォーマットの際にメンテナンス資料も消えてしまうというトラブルです。
メンテナンス用の書類の概要

「会社の共有フォルダにメンテ資料を置きましょう」と提案しようにも、しかし上司のチェックすらされてない資料が共有フォルダに置かれるわけもないので、結局はそういう会社ではエンジニア個人のパソコンでメンテ資料を管理させられたりもします。そして、いつしかメンテ資料が消失しています。
メンテナンス用の書類の概要

この手の資料消失のトラブルを未然防止する簡単な方法は、定期的に、部署の部長課長などや上司などの管理者が、現場エンジニアから上がってきたメンテナンス資料の原稿を、(管理者が)定期的にチェックする必要があります。
メンテナンス用の書類の概要

また、こうやって定期チェックすれば、万が一、メンテ資料消失しても、資料を普段から検査してきた上司や検査担当者の頭の中に記憶が残っているので、ノウハウの復旧が比較的に容易です。
メンテナンス用の書類の概要

しかし、部長や課長などが原稿チェックを面倒くさがっていると、上述のようなトラブルになります。
メンテナンス用の書類の概要

どこの技術系の企業でも、設計図のチェックは念入りに行いますが、しかしメンテナンス用資料のチェックが省略されたりする会社が多くあります。 資料紛失は会社側の自業自得でもあります。
メンテナンス用の書類の概要

なお、上司がチェックを面倒くさがっているという理由でメンテ資料が個人管理されている場合、当然、その資料は印刷などはされていません(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない)
メンテナンス用の書類の概要

なので、退職しなくても、ハードディスク故障などが起きればメンテ資料は消失して一巻の終わりです。
メンテナンス用の書類の概要

退職が決まったときに会社は引継ぎ資料をエンジニアに作成させようとしますが、当然、上述のような技術資料が急に作れるわけもなく、そもそも資料の内容が上司や同格の技術力のエンジニアから検証チェックもされてないので信頼性も不明だし、よって急ごしらえの資料作成は大抵、失敗に終わります。
メンテナンス用の書類の概要

根本的な原因は、メンテ資料のための作成費用を普段から出していなかった会社の態度です。また、この手の会社は、そもそも論として、退職エンジニアより昔の前任者からのメンテ資料すら用意していないのが通例です。そんな杜撰(ずさん)な管理体制なので、大抵の企業では、急ごしらえのメンテ資料の作成は失敗します。会社の自業自得です。
メンテナンス用の書類の概要

つまり資料消失であわてる会社というのは、そもそも、まともにメンテ資料の上司によるチェックもしていなかったという会社であり、いろいろと自業自得です。
「単位動作」という概念

主に機械工学教育の用語なのですが、「単位動作」という用語があります。
「単位動作」という概念

たとえば、熟練工の動作は、一見すると色んなスキルを習得しているので複雑に見えますが、しかし動作のひとつひとつは、たとえば卓上ボール盤なら教科書どおりの卓上ボール盤の使い方ですし、やすりがけ の動作も、教科書どおりの動作です。
「単位動作」という概念

複雑な動作も、教科書どおりの動作を、組み合わせただけに過ぎません。
「単位動作」という概念

そして、その やすりがけ だけの動作の説明も、図や写真などを使って、「手順1:○○をする。」、「手順2:△△をする。」などと一段階ずつ、1ステップも抜かりなく 教えます。
「単位動作」という概念

だから、工業高校や大学の機械工作実習では、教科書どおりの動作をひとつずつ、教えます。
「単位動作」という概念

けっして、いっぺんにまとめて、別種の動作を教えません。
「単位動作」という概念

このように、動作をひとつひとつの単純な動作に分解することを単位動作といいます。
「単位動作」という概念

なぜ、わざわざこんな事を説明するかというと、世間では複雑な物事を説明するときなのに、いっぺんに教えたがる人がいます。しかし、そういう教え方は、多くの開発現場ではNG(エヌジー、ノー・グッド)です。
「単位動作」という概念

残念なことに、インターネット上には、一見すると説明書の文章量が多くても、実態を読むと、このような作者以外でないと操作方法を読み解けないようなダメな説明法をされているツールも、残念ながらネットに多く公開されてしまっています。
「単位動作」という概念

単位動作を意識した解説の書き方は、べつに難しくなく、普通に、 たとえばwindowsのオフィスソフトなどのヘルプファイルや、あるいはオフィスソフトについての市販の操作解説書のように、 「~~をしたい」といった操作目的の種類ごとに一個ずつ手順を段階的に教えればよいだけです。
「単位動作」という概念

単位動作の説明を軽んじる人が根本的に勘違いしていることは、「複雑な動作を練習したほうが、スキルが上達する」という勘違いです。
「単位動作」という概念

むしろ物理学の公式のように、単純で短いものに置き換えたほうが、物事を考える際の部品として使いやすくなるのです。 だから実際の順序は、「単純な動作を見つけ出すために、その何倍もの練習や試作をする」のです。たとえるなら、発明家の努力のようなものです。「99%の努力の上での、1%のひらめき」です。
実社会のデータベースでは過去データは消さない

在庫管理ソフトで、もし在庫部品データで、購入元メーカーで生産中止になったりした部品があっても、一切、在庫データベースからは登録を消しません。
実社会のデータベースでは過去データは消さない

もし消したりすると、次の登録番号の部品との登録情報の連続性が無くなり、登録データが飛び飛びになるので、大変に管理が難しくなるからです。
実社会のデータベースでは過去データは消さない

だからともかく、生産中止部品のデータベース管理では普通、その部品の末尾コメントに「生産中止」などと書き足すだけにして、登録そのものは維持します。
実社会のデータベースでは過去データは消さない

また、自分が使っていなくても、過去の自社製品を購入した客先がその部品を組み込まれた自社製品を使っている場合もありますので、残す必要があります。
実社会のデータベースでは過去データは消さない

だからもし、生産中止でなく単に入力ミスなどで登録済みの部品をまた登録してしまったことが判明した場合も、 最新の登録IDでない限りは、消すのではなく、末尾コメントに「登録ミス。すでにID○番で登録済み。」のような記録を書いて残したままにするのです。
実社会のデータベースでは過去データは消さない

こういうのはデータベースを運用する際の基本テクニックです。
実社会のデータベースでは過去データは消さない

製造業の図面などの「部品表」の番号でも、同じようなテクニックが使われます。設計変更により過去の廃止になった部品に当てられていた番号は、消すのではなく、新規の番号を確保して、その新規番号に代替の新部品を割り当てるというテクニックです。
実社会のデータベースでは過去データは消さない

また、「登録IDを最整列して並び替える」なんてことは、一切、しません。そもそも、在庫ソフトにそのような機能も原則、ありません。
実社会のデータベースでは過去データは消さない

なぜなら、すでに紙に印刷した実物の台帳に保管されている登録ID番号までを、在庫管理ソフトで書き換えることは不可能だからです。
実社会のデータベースでは過去データは消さない

一般に在庫の台帳は小さな事業所でも数千種類の在庫部品があるので、台帳にあるその数千種の再チェックをするのは時間の無駄なので、並び替えはしません。もし在庫番号の並び替えをすると、「本当に並び替え後の番号が合っているか?」などのチェックの手間が生じます。
品質の検証

製造業でもIT企業でも品質の検証は、部品ごとの検証と、全体の組立てをしたあとの検証という、最低でも2段階です。
品質の検証

少なくとも、自動車業界はそうです。
品質の検証

個々の材料部品などは、実際に引張り試験や荷重試験などを実際に物理実験を行い、部品の耐久値が規定や要求仕様を満たしているかを、事前に確認します。そして自動車の走行試験や衝突試験などは、実際に部品を組み立てて製品の状態である自動車にしてから走らせて見るしか、方法はありません。
品質の検証

チェックにおいて、シミュレーションなどは無駄です。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もありません。
品質の検証

「チェックの最終確認においてシミュレーションが無駄」といのは、これは自動車業界だけでなく、航空宇宙などでも同様です。日本のJAXAは「はやぶさ」の部品モジュールの開発において、実際に部品を組み立てたうえでの(シミュレーションではなく)物理実験をしています(※ 講談社ブルーバックス『小惑星探査機「はやぶさ」の超技術』で確認できます。)。
品質の検証

また、産業技術総合研究所での測定の国家標準器開発などでも同様の手法であり、実際に測定器を製品として組み立てた上での物理実験をしています(テレビ番組では、TBS科学番組『夢の扉』でメタンハイドレート採掘の産総研の研究者が、そうシミュレーションの問題点を指摘しました)。
品質の検証

ソフトウェアの開発では原理的に物理実験は無理ですが、それでも不具合対策の確認は、最終的には、実際にそのソフトをユーザー視点で使用してみる「実践」/「試用」しかありません。
品質の検証

ソフトウェア業界だと、個々の部品ごとにチェックすることを「単体テスト」といいます。一方、全体的に組みたててみてチェックすることを「ビッグバンテスト」と言います。
品質の検証

さて、チェックにおいて、シミュレーションなどは無駄であり。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もないのでした。
品質の検証

ではシミュレーションの意義は何かと言うと、工業系に強いライター(「文筆家」の意味)の山根一眞『メタルカラー』シリーズのどれかに書かれていると思いますが、意義はけっして直接のチェックではなく、既に行った物理的な検証実験をもとにそれをシミュレーションと照らし合わせることにより相互検証することで、検証回数を減らすことにより費用節約するのが目的です。
品質の検証

たとえばシミュレーションなしでは20台の機械装置を耐久実験のため壊さないといけない工程であると仮定して、もしシミュレーションありなら耐久試験で壊すのは12台ですむ工程にできるなら、今後の自社の新製品では8台ぶんの費用が節約できます。そういうコストダウン投資のためにシミュレーションをするのです。
品質テスト

ソフトウェアのテストは、IT企業では、よく新人がやらされる仕事でもあります。新人研修に組み込まれていたり、研修明けによく与えられる仕事でもあります。
品質テスト

なぜなら、自社ソフトウェアの内部構造の知識が乏しくてもテスト自体は可能だからです。
品質テスト

製造業などでも、多品種少量生産の設備機械そのものの生産では、たとえば簡易的な耐久試験などのために「実機のボタンAを押した後に画面遷移後にボタンBを押すのを、50回繰り返す」みたいな簡易的かつ長めの時間の繰り返しテストは、よく新人の仕事です。(なお、50000回の繰り返しみたいにテストが長すぎると人間じゃ無理だし(機械で繰り返すことになる)製品が磨耗して壊れたり製品寿命が大幅に減るので、せいぜい人間でも可能な500回くらいまでにとどめて、人間がテストしたりします。)
品質テスト

どの業界でも、テストのうち、時間の掛かる繰り返し試験は、よく新人に与えられる仕事です。
品質テスト

いちおう、設備機械の組立て直後の段階で、「ボタンAを1回だけ押すテスト。ボタンBを1回だけ押すテスト。」みたいな(繰り返しでない)短時間テストは、機械を組み立てした生産者本人が現場で行います。しかし、「500回繰り返す」みたいな仕事は長いので、新人がテスターを行うのがよくある会社風景です。
オーバーエンジニアリングを避ける

「オーバーエンジニアリング」(over engineering)という用語があり、善かれと思ってもか、余計な設計をしてしまう事です。」
オーバーエンジニアリングを避ける

たとえばソフトウェアの設計の場合、あらゆるバグを想定して個別に対応したコードを書こうようとしてしまうと、コードが長大になってしまい、保守性がいちじるしく低下してしまいます。
オーバーエンジニアリングを避ける

システムのあらゆる部分にバックアップを持つのも、時間的にも費用的にも不可能であり、オーバーエンジニアリングです。
オーバーエンジニアリングを避ける

製品と寸分も違わぬデザインパターンを追求しようとして、ろくに実装もしないのもあります。また、そのような発想で書かれたマニュアルは、膨大な学習コストが必要であり、実用性が乏しいです。
オーバーエンジニアリングを避ける

最小限の機能だけのプロトタイプを作る手法です。
オーバーエンジニアリングを避ける

生命などの安全にかかわるものでもないかぎり、失敗を許容しましょう。
オーバーエンジニアリングを避ける

機能が実際に必要になるまで追加しない方法です。
オーバーエンジニアリングを避ける

ソフトウェアの場合、あとからでも比較的に容易に追加できることが多いので、こっちのほうが良いでしょう。
オーバーエンジニアリングを避ける

ただし、航空宇宙や造船などは別かもしれません。
工学では現状、「設計図とは何か?」といった理論は存在しません。情報工学でも、「IT企業の仕様書をどう書くか?」という書籍は、ほとんどありません。大学生向けの情報工学の参考書でも、まず触れられてない分野です。
本ページでは現状では参照していない文献ですが(2022年2月11日)、設計の理論を紹介していると思われる関連文献として『岩波講座 現代工学の基礎』があります。ある程度、設計についての抽象的な説明があるかもしれません(たとえば『岩波講座 現代工学の基礎〈1〉設計の方法論』(2000/5/10)あたり)。 しかし岩波のこの本はそんなに厚くないし、ソフトウェアも含めては説明していなかったかもしれません(手元にないので確認できません)。
ITの場合、ビルド手順の記録が必要

集団でソフトウェアを作るとき、そのソフトウェアのビルド方法を仕様書に書かないといけません。(これは製造業の設計図などには無い、IT業界の独自の事情です。)
ITの場合、ビルド手順の記録が必要

ビルドとは、実行ファイルを作ることです。
ITの場合、ビルド手順の記録が必要

Visual Studio などのソフトウェア開発環境ツールは大抵、ビルド機能もあるので、最低限、作者が実際に使用した開発ツールを書いておく必要があります。ビルドに必要としたソフトウェア(ビルド実行ソフトや、必要なライブラリ)、ビルドのためのコマンドや操作手順なども、ひとつひとつ詳細に書くべきです。
ITの場合、ビルド手順の記録が必要

実際に自分がそれらビルド手順のとおりにソフトウェアだけをインストールと設定を試してみて、もしその手順の指定に従えば(従うのが知識的に簡単かどうかはともかく)、とりあえずビルドできて、実行ファイルを生成できる程度には、書く必要があります。
ITの場合、ビルド手順の記録が必要

ソースコード公開サイトなどのプログラムを見ると、説明書を見てもどこにもビルド方法や実行環境が書かれておらず、ビルドできずに使いようのないコードが時々あります。ビルド不可能ではあまり有意義なソースとは言えないでしょう。
必要な書類

一般のIT業界や製造業の場合、集団作業で必要となる書類は、主に下記のセットでしょう(編集者Sの推測)。
必要な書類

設計図とは完成図のことです。
必要な書類

さて、一般のIT企業や製造業では上記の設計図~参考資料に加え、必要に応じて「説明書」、などを加える場合もあります(業界や会社によっては、説明書は上記セットとは別の本棚などに分離する場合もある)。この4〜5点セットの書類を、集団作業の便宜のために、将来にわたって残していきます。(土建や製造業などの堅い業界の場合は、「設計図書」(せっけい としょ)、などの名前で管理されることもあります)
必要な書類

娯楽産業ではない一般のIT企業や製造業でも、製品の企画に至った経緯を記した書類を、大元のアイデアを考えた会社の側では残しています。(ただし一般企業の場合、社内プレゼン用資料の流用の場合もある)。上記セット一覧のうちの「設計図」はゲーム業界では「仕様書」に対応しており、「企画に至った経緯を示した書類」は「企画書」に対応しています。一般企業では書類の名前は、「企画書」ではない場合も多く、業界や会社によって異なります。
必要な書類

企画書だけでなく、マトモな科学論文とかでも、既存品と今回の製品とはどう違うのかという構成が好まれます。つまり、論文なら「何を新発見したのか? → いままでの理論ではどうだったか?それと今回の新発見とでは何が違うか? → 発見のプロセスや詳細など」といった構成が、マトモな科学論文のあるべき構成です。
必要な書類

また、メンテナンスのための図面として、「フロー図」とか「モジュール図」や「システム図」等、設計図としての目的でない将来的なメンテナンス改修などを見越して作成される図を、保存しておく必要があります。
必要な書類

一般IT業界の仕様書の書き方の本やwebサイトを見ると、「要件定義書」「内部設計書」「外部設計書」「ネットワーク図」「業務フロー図」「インターフェース設計書」「モジュール設計書」などの色々な書類・図面がありますが、発注元で最低限必要なのは上記4点セット(完成予想図、メンテ用資料、企画書類、外部資料)でしょう。IT業界特有の設計書類も、完成予想図またはメンテ用資料を作成するため手段に過ぎません。
「設計図」とは完成図である

では「設計図」とは何かというと、製造業の場合での「設計図」の意味を説明すると、それは「完成予想図」です。「完成予想図」というところがポイントで、実は生産方法などは指定していないのです。なので設計図だけでは、実は何も生産できないのです。
「設計図」とは完成図である

なので設計図に加えて、現場で必要な生産方法の技術をもった技術者が、さらに必要です。なので、設計図はあくまで、最低限必要な情報でしかないのです。実際には、設計図以外にも、生産方法についてのさまざまな情報が必要です。
「設計図」とは完成図である

ですが、どこの業界でも、生産方法については図面化しないか、たとえノウハウを部分的に文書化していても社外秘にしていて非公表なのが通常です。
「設計図」とは完成図である

IT業界でも、あるソフト製品のプログラミングの具体的なノウハウについては、その製品の「仕様書」には記載されないのが通常です。
「設計図」とは完成図である

完成予想図として「部品図として、このような寸法(各部の長さ)・形状・材料をもった部品を図面の指定どおりに作れば、あとは組立図に部品どうしの相互位置が書いてあるので、(組立図の)その位置指定とおりに取り付ければ、必ず完成しますよ」
「設計図」とは完成図である

という状態にまで、部品図と組立図の状態をそれぞれ完成予想図の形で書き上げていくのが、図面を書くという事です。
「設計図」とは完成図である

技術的の企業でいう「設計図」の意味は、おおむね、こういう意味です。
「設計図」とは完成図である

もし、納品される品物が仕様を満たしてない場合、けっして合格品としてはいけず(つまり「検収」してはいけず)、(発注者は)協力会社に作り直しを要求します。この仕様違反のさいの作り直し要求はIT業界にかぎらず製造業でもどこでも、受け入れ検査は通常、そういう仕組みです。
「設計図」とは完成図である

ソフトウェアを作る場合も、最終的に製品の完成の段階では、最低限このような水準にまで、設計図を作りこんでいきましょう。(ただし、ソフトウェアには「寸法」など形状の条件は無いので、そこはアルゴリズム的な条件に意味を読み替えること。)
「設計図」とは完成図である

製造業では図面をもとに見積もりをします。基本的に技術系の業界では、設計図をもとに見積もりが行われるます。
「設計図」とは完成図である

学生は企業社会を知らないと思うので説明しますが、コンピュータ業界にかぎらず、そもそも製造業なども含む技術系の業界で、設計から生産までの流れがどういう工程で行われているか、説明します。
「設計図」とは完成図である

まず、なにかの設計図では、具体的な生産方法は指示しません。たとえば、組み立てた後の形状がどうなってるかは組立図(くみたてず)に描いても、しかし、「どうやれば組み立てられるか?」とかの情報は一切、そういう事については『設計図』では指示しません。
「設計図」とは完成図である

ともかく、なにかの設計図は通常、その製品の完成図である必要があります。製造業で「図面」と呼ばれているものは、こういった具体的な完成予想図のことです。
「設計図」とは完成図である

そして、その完成図はいくつもの部品から成り立っているのが普通なので、完成品をいくつかモジュールごとに分解した部品図(ぶひんず)をいくつも作成して、それぞれの作成担当の作業者に渡します。
「設計図」とは完成図である

こうすることで、分業もしやすくなり、一石二鳥です。
「設計図」とは完成図である

基本としては、設計図とは、設計図だけを見ても、あいまいさの無い状態で完成品の満たすべき具体的な条件が分かるようにしなければなりません。
「設計図」とは完成図である

さて、製造業などでも、「図面」という完成予想図があります。
「設計図」とは完成図である

よく、IT業界でいう「現場で見つかった仕様書の不具合を仕様書にフィードバックする」とか言う表現は、おそらく完成予想図のような書類のことを指していると思います。
「設計図」とは完成図である

なぜなら製造業でもフィードバックは図面に対して行います。なので、製造中に不具合が見つかれば、どんどんと図面が改訂されてゆくし、そのために設計者は現場に立ち会うし、場合によっては設計者みずからが製造もしていきます。
「設計図」とは完成図である

技術系の業界では一般に、書類で作業指示を出すときに、いちいち、けっして具体的に、「作業員であるアナタは、○○のコンピュータの△△ボタンを押して、××をしてください」のような指示は出さないです。
「設計図」とは完成図である

指示はそう出すのではなく、図面のような完成予想図(ただし決定稿)を出して、「この完成予想図のとおりになるように作っておいてください。」というような指示が出ます。
「設計図」とは完成図である

さて、IT業界の場合、末端の部品プログラム完成予想図を描く前に、普通の設計では既にフローチャート図または状態遷移図などといった、全体的なシステムの図面を書くのが望ましいとされています。(以降の説明では、言い回しの省略のため、フローチャート図または状態遷移図を単に『フロー図』または『フローチャート図』と略記する。)
「設計図」とは完成図である

なので、もし横断的な説明をしたければ、このフローチャート図を作るとき、このフローチャート側に説明を追加するとか、あるいは、フローチャート図を参照する形で別途の参考図を追加するとかすれば、良いかもしれません。
「設計図」とは完成図である

こうすれば、もし末端部品プログラムを訂正することになっても、訂正の必要のある図面は、末端プログラム図面と、その直接の上流のフロー図あるいはフロー別途参考図だけのたった2枚に限定できますので、訂正の手間を減らせるので効率的です。
「設計図」とは完成図である

なお、もしかしたらIT業界でも、状態遷移図やフローチャートを描かないで設計する事態も企業によっては横行しているかもしれませんが(原理的には、状態遷移図やフローチャート図が無くても、エクセルなどで作成した部品プログラム仕様とその組み立て仕様のエクセル形式の完成予想図だけでも、原理的にはソフト設計できてしまう)、しかし、こういう状態遷移図などの画像での説明を省いた設計では設計ミスが発生しやすく、結局、再設計などの手間が掛かってしまうのがオチです。
「設計図」とは完成図である

なお、一枚の仕様書の中では、内容の重複はオッケーです。
「設計図」とは完成図である

たとえば、機能の似たモノを2個つくるとき、
「設計図」とは完成図である

2個目の説明では、「○○については△△と同じ」のように、「~~~と同じ」というふうに説明できるから、です。製造業でも、一枚の図面に正面図と側面図の2方向の図のある場合、側面図に参照値として正面図の値を書くと、正面図の設計変更にともない、ときどき側面図にある参照値を修正し忘れるミスがあります。)
「設計図」とは完成図である

なので、よほど仕組みの複雑な難しい製品でないかぎり、なるべく2回目以降の説明では具体的内容は書かないのでおくのが、設計の図面では修正モレを防げるので安全です。
「設計図」とは完成図である

ただし、これはあくまで、設計図面の書き方です。教本や指導書などの書き方とは、設計図面の書き方は、違います。もし、新人むけの指導書や教科書・教本を書く場合には、やや重複のある内容でも何度も説明して覚えさせましょう。
要求事項書

要求事項は、「○○してもらいたい」という指定も必要ですが、ソレとは別に、できれば、「なんの目的で、そういう指定をしているか?」などの理由も書いてあると、ニュアンスが正確に伝わるので、伝達ミスなども減ります。
要求事項書

企業秘密などで無いかぎり、できるだけ、目的も平気したほうが良いでしょう。
要求事項書

要求事項の書類には、要求には理由も併記するのが望ましいと指導されているようです。
要求事項書

さて、一般IT企業で要求事項書の話題に戻るとして、また、意外と伝達側が設計ミスをする場合もあるので、目的も書面で伝えておくことにより、相手先の人が、気を聞かして検証してくれます(べつにボランティアで検証してくれるわけではなく、どっちみち相手先が設計中に結果的に検証することになるで、だったら要求事項に目的も書いておいたほうが効率的になる)。
要求事項書

なんども指摘するが、「要求事項」だの「設計図」だの何種類も作る書類セットの書き方では、説明が重なって多いぶんには問題ないのです。(ただし、要点などを抜き出した簡略版の説明も必要。)
要求事項書

大は小を兼ねます。
要求事項書

なお、社会人の情報伝達では、結論を先に言うのがマナーなので(詳しくは『中学校国語/現代文/報告書の書き方』)、要求を先に伝えてから、理由を直後に伝えます。つまり、文章のテンプレートとしては、
要求事項書

のような順番になります。
要求事項書

設計図の各書類は一般的に外部には非公開なので、書類セットくらいでしか体系的な説明をできないので、むしろ別書類にて説明の重複などがあって相互検証できるくらいのほうが、安全なのです。なお、要求事項の段階では、あまり細かく事項書を作りすぎずに、そのぶん実際のプログラムの開発を早めましょう。
データ台帳

重要なことは、一般のソフトウェア開発などでの実務では、なんらかの特殊な数値データが組み込まれている場合、台帳と実物プログラムとによってダブルチェックをするという事です。(ゲームだけでなく、製造業の組み込みソフト開発などでも、台帳などによってダブルチェックをしています。)
データ台帳

IT業界では、ダブルチェックを軽視している人が多いですが(たとえば電卓とパソコンソフトとの計算結果のダブルチェックを批判する言説がネットに多い)、そういうのは製造業や組み込み業界などでの実務を知らない知ったかぶりのタワゴトなので無視しましょう。
データ台帳

マトモな業界では、プログラムの検証のため、そのソフト以外およびそのソフトを動かしているハードウェアとは別のデバイス(電卓でも良い)を使って、ダブルチェックをするのが常識です。(※この常識には出典を出せませんが(企業秘密などに関わるので)、しかしダブルチェックを軽視する側の主張も満足な出典を出せていないので、対抗的にこの文を残します。)
データ台帳

さて、入力されたハズのデータの台帳のような内容の一覧の書類が、一般の技術系企業では必要です。業界で「台帳」と言うのかは知りません。名前が無いと困るので、とりあえず土木工学ではこういうのを「○○台帳」というので、それに習って「データ台帳」という題名を本セクションでは、つけているだけです。なので、IT企業では別の呼び名かもしれません。
多項式近似

測定値などで、入力変数が一変数なら、エクセルなどを用いて多項式近似が出来ます。
多項式近似

一般にIT業界での実務の多項式近似では、原理的には9次でも20次でも、どんなに次数が高くても(おそらく int 整数型の限界くらいまで)計算できてしまいますが、
多項式近似

しかしIT業界などの実務では人間の検算などの手間を減らすために、なるべく、せいぜい2次式や3次式といった、低めの次数におさえて利用するのが、IT企業では普通です。
多項式近似

もし先端科学のための多項式近似なら、9次を超えるような多項式近似をするような場合もありますが、しかし、一般の企業では、そこまでの多項式近似は不要ですし、むしろ検算などの管理の手間が増えるので、9次のような多すぎる次数は嫌われますので、なるべく2次ていどに抑えましょう。
バグあると人の死ぬ業界

ゲームではバグがあっても、人は死にません(過労自殺などを除けば)。なので、アイデアが思いついたら、どんどんとプロトタイプで試してみましょう。
バグあると人の死ぬ業界

ですが、他の業界だと、バグがあると人が死ぬ場合もあります。たとえば、製造業での、組み込み機器などがそうです。
バグあると人の死ぬ業界

書籍で紹介されている事例だと『メタルカラーの時代』シリーズ(山根一眞(やまね かずま)による取材)で、 「日本ユニシス」というIT企業がかつて、提携している別企業のNC工作機械に向けた組み込みソフトの開発で(組み込みソフト部分をユニシスが開発)、開発テスト中のバグにより工作機械の刃物が本体にぶつかって折れて飛んできて、あやうく人が死ぬところだった、 ・・・という感じの事例がインタビュー先のプログラマから紹介されています。 それまで日本ユニシスおよびその担当プログラマーでは、組み込みの仕事はほとんど扱わずに、どちらかというとIT業界内での顧客を仕事をしていたので、そういう人が死にそうな事例に経験することがなかったので、製造業の組み込みソフトでは特にバグおよびバグ予防に対する考えをIT業界内の仕事とは変えなければならない必要があることに気づかされた、とユニシスの技術者はインタビューで述懐しています。
履歴の管理

一般のIT企業でいう仕事の「仕様書」では、開発前の段階で書いた要件定義書や設計図(完成予想図)やコード解説書など」を、ソフト完成後にも残す必要があります。
履歴の管理

なぜなら、開発前~開発中の経緯を、上司や他部署に事後的に報告したり、のちに入社してくる後輩などに教育としてソフト開発時の出来事を教えるためです。
履歴の管理

このため、こういった仕事の書類には、著者や、著作・改訂の日時(「改訂日: 2018年8月30日」)や改訂者(「改訂者: 山田太郎」)などの履歴(りれき)も記載する必要もあります。
履歴の管理

のようになります。(企業では、こういうページのパソコンでの文書管理は、エクセルなどの表形式データになってるのが普通。)
履歴の管理

さらに改訂の際には、それぞれの版の改訂内容の要約を書く必要すら、あります。
履歴の管理

アマチュアの場合なら、『メモ帳』アプリなどで説明する場合もあるかもしれないので、たとえば
履歴の管理

のようにアレンジする必要があるかもしれません。
履歴の管理

アマチュアのゲーム製作の場合、エクセルまでは不要でしょう。
ファイル名の冒頭番号

ゲームを例に説明します。
ファイル名の冒頭番号

ゲーム産業に限ったことではないのですが、企業でのパソコン内での、ファイル名やフォルダ名の管理手法として、たとえば何かの説明書きのファイルがいくつもある場合、
ファイル名の冒頭番号

などのように番号順をつけて命名することもあります。「01_キャラクター設定」でひとつのフォルダ名です。なぜこのように番号を冒頭につけるかというと、もしパソコン上で名前順に並び替えたときに、必ず狙った順番どおりにさせるためです。
ファイル名の冒頭番号

そして、たとえば「キャラクター設定」フォルダ内に、さらに
ファイル名の冒頭番号

のように、さらに 番号づけの設定があることもあります。
ファイル名の冒頭番号

たとえば、「ゴンザレス」というキャラが主人公のゲームの場合、彼が最初に来てもらわないと困るわけです。もし番号が冒頭に無いと、「ゴンザレス」よりも「アルベルト」のほうが五十音順では先に来てしまいます。
ファイル名の冒頭番号

しかし、上記のように番号を冒頭につける方式を採用することで、あとでどんな名前の新キャラクターを追加しようが、必ずファイル検索の名前順検索では「ゴンザレス」が最初に来るようになるのです。
ファイル名の冒頭番号

なお、業務用のファイルでは一般的に、冒頭番号と項目名とが別々のものであることを強調するために、半角スペースを使わずにアンダーバー「_」を使うのが一般的です。
ファイル名の冒頭番号

IT企業に限らず製造業でも、たとえば図面ファイルでは
ファイル名の冒頭番号

などと、冒頭番号ごと名前をつけてフォルダ管理するのが一般的です。
ファイル名の冒頭番号

フリーソフトのファイル構成などでも、本ページはゲーム教科書なのでゲームに置き換えて説明しますが、
ファイル名の冒頭番号

のようなファイル構成のフリーソフトも時々、見かけます。
説明書

フリーゲームなどは、あまり説明書が細かくかかれないので、気にする必要はないでしょうが、一般IT企業のソフトウェア説明書や製造業の組み込みソフトなどは、もっと細かく一通りの操作方法を説明します。
説明書

イメージしやすさの都合で本ページでは、製造業などの組み込みソフトを例に、説明書の書き方を説明します。
説明書

なんと、組み込みソフトの説明書を書くためには、操作テストが必要です。
説明書

だから例えば工場の生産ライン用の設備に組み込まれてる組み込みソフトの説明書なら、その説明書の文面は、工場で下書きしてるわけです。
説明書

オフィスで下書きするのではなく、工場で下書きするのです。なので、工場にノートブック(文房具)と筆記用具(要・赤ペン)を持ち込んで、そこで説明書の文面を下書きするわけです。
説明書

たいていの新人は、実機での操作テストに気が引けがちです。
説明書

実機で操作テストばかりしてると「周囲の先輩から『この新人は書類も読まずに実機をいじって遊んでる』と周囲に見られるんじゃないか?」と不安になったりとかして、実機によるテストを遠慮しがちです。また、仕様書は読んでて勉強になりますので、ついつい仕様書ばかり読みがちで、テストを遠慮しがちです。
説明書

しかし、それは新人特有のよくある勘違いなのです。説明書を書く場合にも、実機でテストプレイをするべきなのです。
説明書

なので、下書きが終わったら、さっさと実機テストをするべきなのです。
説明書

まず、仕様書などをもとに、説明書の大まかな章や節などの構成を、仮決めします。
説明書

大まかなページ数などの仮決めのために、仕方なく仕様書を見ながら、仕様書から想定されるハズの操作方法を書きます。
説明書

この下書きは、これはこれで必要であり、あとの操作テスト時にチェックすべき項目を示したチェックリスト的な意味合いもあるので、とりあえず、実機プレイなしですが下書きをします。
説明書

ですが、この想定した操作方法は、まだ何のテストもしてないので、高確率でミスが含まれています。
説明書

なので、下書きした説明書のプロトタイプと筆記用具(赤ペン)を持ちながら、実機のある現場に移動して、到着したら実機で説明書どおりにテストプレイしながら(絶対に説明書を見ながら、杓子定規に説明書どおりにプレイします)、実機操作中に発見した説明書のミスを、赤ペンで下書き説明書に、追記でメモ書きしていくワケです。
説明書

このように仕様書ばかり読んでないで、さっさとテストします。
説明書

だから、説明書を書くオフィスは、そういうテストが気軽にできる環境の近くに存在する必要があります。
説明書

また、組み込みソフトの説明書を書く技術者は、工場の組み込みソフトを書くなら、技術書の服装としてはブルーカラーの作業着で仕事してるわけです(背広ではないです)。作業着でないと原則、現場に入れないので
説明書

組み込みソフトは、機械などに組み込まれてるわけですから、安全が確保されていて可能な限り、仮想化などではなく、実機でテストします。 (仮想化でテストすると二度手間になります。なので可能なら最初から実機でテストしたほうが早いです。)
説明書

このような仕事を、よく新人がやらされます。
説明書

新人は消費者目線に近いので、どこの業界でも、新人がよくテスターにさせられることが多いのです。
説明書

同様の理由(消費者目線)で、説明書を書く仕事も、どこの業界でも、新人がよく説明書を書かされます。
説明書

子供向けの玩具で電子玩具の説明書などだと、場合によっては説明書の文面が子供口調(「~だよっ!」とか「~だね!」みたいな口調)で説明が書かれていたりしますが、けっして説明書を書くお仕事が子供の学校の図工みたいな作り方をしてるワケではないでしょうし、おそらくは実際の執筆手順は上記の組み込みソフトの説明書のような感じの手順で説明書を書いていってると思われます。説明書の口調という表面にダマされないようにしましょう。
説明書

ああいう子供口調やら女口調の説明書は、集団作業の場合なら、下書きの段階での口調は、普通のビジネスマン的な書類の口調で書いているか、たとえ くだけた下書きの場合でも普通の大人のくだけた口調で下書きを書いているのであって、あとの工程で口調だけ入れ替えて子供口調や女口調に入れ替えるという手間を掛けていると思われます。けっしてイキナリ、子供口調とかで書類を書きはじめるわけではありません。
パラメータ調整の理論

たとえば機械設計の業界で昔から言われている教訓として(なるべく新規設計では)「材料と構造を同時に変えるな」というのがあり、日経クロステックのwebサイトでもそう紹介されています。引用元の日経クロステックの記事では「2つ以上のものを同時に変更するときは、組み合わせによる問題が起こりやすいことを示唆している」と指摘されています。
メンテナンス用の書類の概要

完成形をつくるだけの「設計図」的な「仕様書」だけでは、バグ発生時や設計ミス発生時などのさいの修理が不可能です。
メンテナンス用の書類の概要

また、ITソフトウェアなら、移植などの際に、もしソースコードだけしかなくて書類不足だと、「コードがどのように動いているのか?」を後任の人が把握できずに、移植困難になってしまうトラブルもあります。
メンテナンス用の書類の概要

前任者が会社を辞めてしまっている場合などもあるので、色々と書類が必要でしょう。こういうことから、もし下記のような資料が無いと、不具合の発生時に、修理のための設計変更で、どこをどうイジればいいか特定できず、困ります。
メンテナンス用の書類の概要

というか、残念ながらこういう資料の不足している職場は多く、なので日本のIT技術者は困っています。
メンテナンス用の書類の概要

上記書類のうち、特に「部品と機能の対応表」、「コード解説書」は、メンテナンス目的以外にも、設計図のチェックにも利用される。なので、そういう目的もあるので、ぜひ作成しておくのが望ましい。
メンテナンス用の書類の概要

「部品と機能の対応表」のことを、IT業界で何と言うのか、このページの著者は知りません。しかし、ともかくそういう対応表がないと、メンテナンスが後々に困難になります。
メンテナンス用の書類の概要

発売後の(一般のIT企業では)ソフトにも、修理・メンテナンスが不可能になる場合があります。
メンテナンス用の書類の概要

そのため、製造業などの組み込みソフトなど、まともなIT業務では、ソースコードの内部構造・全体構造のコード解説書とでも言うべき書類があることが望ましいです。(特に名前は決まっていない。また、中小企業などでは作成しない場合もある)
メンテナンス用の書類の概要

一般のIT企業では「内部設計書」や「プログラム設計書」などの名前の場合もありますが、しかし既に設計図などで大まかな指定はできていますので、設計の時点では、これらの「設計書」が不要な場合も多くあります。
メンテナンス用の書類の概要

これらの書類の目的は、どちらかというと、設計よりも、後日に読み返したときのメモ書きです。主要な変数、主要な関数などは、第三者が、なんのドキュメントも無い状態でその意図を読み取るのは、なかなか手間が掛かります。なお、最終製品やあるいはコードだけから逆に設計書や設計図などを書き起こすことを「リバース・エンジニアリング」と言います。リバース・エンジニアリングは、本来なら、後任者などには、させるべきではないのです。
メンテナンス用の書類の概要

大目的として、完成後のメンテナンスなどの際に、リバース・エンジニアリングという手間のとても掛かる作業を、けっして後任者にしないでも済むように書類を残すのが、正しい書類作成および書類管理のありかたです。これが、前提の大目的です。これさえ押さえてくれれば、ほぼこのページで言いたいことは尽くされています。このページの残りの説明は、単にイメージを具体化するためのケーススタディです。
メンテナンス用の書類の概要

会社でリバース・エンジニアリングの手間の発生が起きるのは、経営者にとっても時間と予算のロスでしょう。また、リバース・エンジニアリングをさせられる側である社員も、利益を生み出すわけではない作業に時間を多く取られ、とても負担です。なのでとにかく、リバース・エンジニアリングの発生予防が必要です。
メンテナンス用の書類の概要

で、具体的にどうすればいいかというと、リバース・エンジニアリングの発生を防ぐためには、なんらかの方法で、少なくとも主要な変数や関数と、その設計意図の対応表のようなものが必要です。
メンテナンス用の書類の概要

(完成図である)設計図だけでは、このような機能の解説をするのは不可能または困難なので、さらに変数・関数と、設計意図との、対応表のようなものが必要です。この対応表のようなもののことを本wikiでは「コード解説書」と呼んでいます(IT業界で何と言うのか知りません)。(設計図だけでも機能の解説を出来ているなら、その部分は解説書に書く必要はありません。)
メンテナンス用の書類の概要

要するに、機能と部品との対応表も残すべきだという亊です。「この部品、どの機能に対応してるの?」ってのが分かればいいのです。
メンテナンス用の書類の概要

異業種の例ですが、下記の2つの回路の図面を見比べてください。
メンテナンス用の書類の概要

どう比べても、右の「フロー図」のほうが、仕組みが分かりやすいでしょう。もし回路設計の専門外の素人が上記の回路図面を見ても、フロー図のほうなら機能が一目瞭然です。
メンテナンス用の書類の概要

このように、部品と機能を比べる書類があれば、とても後任者がラクになります。
メンテナンス用の書類の概要

また、このような部品と機能の対応の書類を作っておくことで、設計ミスの防止にもつながります。
メンテナンス用の書類の概要

上記の図面の例は、電気回路の設計の業界のハナシなので、ITではないですが、ともかく、こういう部品と機能の対応表があると、仕事がいいカンジです。
メンテナンス用の書類の概要

「フロー図」だの「コード解説書」などの名前はどうでもいいです。重要なのは、部品と機能の対応表を残しておけ、という事です。
メンテナンス用の書類の概要

逆に言うと、部品と機能の対応が分からないような書類ばかりを作っていても、無駄です。
メンテナンス用の書類の概要

けっして、やみくもに「○○設計書」のような名前の書類をいくつも残すのではないべきです。目的である、「部品と機能の対応表」を忘れないようにしましょう。
メンテナンス用の書類の概要

IT業界でこういう書類を残しているか知りませんが、少なくとも電子回路の業界では、こういう書類を残しています。けっして、(ブラック企業だらけだと悪評高い)日本IT企業の習慣のマネではなく、世界に冠たる競争力をもつ日本のB to Bの電子機器の製造業の手法をマネしましょう。
メンテナンス用の書類の概要

一般の企業でのITソフトは、発売後から10年後や20年後にもメンテナンス等が必要な場合があるので、コードの全体構造の解説書が必要なのです。たかが1~2年で流行の廃れるソフトの管理手法なんか、手本にしてはいけません。
メンテナンス用の書類の概要

コード解説書を書かない場合、それでも将来的なリバースエンジニアリング予防のために解説を残したい場合には、おそらくですが、代わりに「仕様書」などの既存の種類に流用で、変数名や関数などの指定を記載したりする必要が生じるかもしれません。ソフトウェアの設計図(完成予想図)はその性質上、解説などはあまり長く書けません。それはそれで一つの方法です。勤務先などに応じて、うまく方法を選んでください。
メンテナンス用の書類の概要

しかし、個人製作ソフトの場合、仕様書は無いのが普通なので、簡易的にコード解説書を書いたほうが早いかもしれません。プログラミングは、仕事や学業などの都合で中断される場合もありますが、再開後に、中断前のアイデアなどを思い出すためにも、コード解説書は書かれていると便利です。(コレがないと、時間が経つと、ほぼ作業内容を忘れる。)
メンテナンス用の書類の概要

さて、経団連企業などの東証一部の上場企業のIT業界の人が「仕様書を書かないと、あとでコードの仕組みを忘れる」とか言ってるのは、きっと、このコード解説書のことでしょう。経団連発言の時代的な文脈的に、けっして要件定義書とか完成予想図とかのことではないハズなので、勘違いしないようにしましょう。
メンテナンス用の書類の概要

このコード解説書の書き方には、けっして、決まった書き方がありません(なので、市販の入門書では、紹介されてない)。ですが、ともかく、経団連企業とかの技術系企業の設計部門では、こういう書類も書くのが望ましいとされています。
メンテナンス用の書類の概要

重要なことは、コードのどの部分が、ソフトウェアのどのような機能を実現するために、何を構成しているかと言った情報を、コード解説書または仕様書などで残すことです。
メンテナンス用の書類の概要

システム構造を解説するには、要するに変数名や関数名や、モジュールが、設計図に示した設計意図にどう対応しているかを、記載できれば良いのです。こういった大目的をまず忘れないようにしましょう。
メンテナンス用の書類の概要

では、どうやったら、こういう解説をできるのかを、これから考えていきましょう。
メンテナンス用の書類の概要

ソフトウェア開発前には実際のシステム構造(プログラムをどういう仕組みにしたとか、変数名をどうつけたか、とか)を書くのが難しいので、ある程度、開発が進んでから、開発中にシステム構造を書くことになります。
メンテナンス用の書類の概要

このコード解説書には、決まった描き方がありません。(なので、一般むけの「仕様書の書き方」入門書では、紹介されていない。)
メンテナンス用の書類の概要

なお、この「コード解説書」書類の呼び名は特に決まっていません。呼び名が無いと不便なので、とりあえず「コード解説書」と呼ぶことにします。
メンテナンス用の書類の概要

まず、ソフトウェアのシステム構造を解説する場合、どのファイルがエントリポイント(コンパイル時に最初に呼び出されるファイル。Main関数などがある)なのか、そういうことから、コード解説書に書いてください。
メンテナンス用の書類の概要

C言語にはファイル分割という機能があり、ソースファイルを複数のファイルに分割できますので、実際のソフトウェアではファイルが何種類もできます。
メンテナンス用の書類の概要

なので、コード解説書にエントリポイントがどのファイルなのかを書いてないと、いちいち読者がファイルを開いて読まないと、どのファイルが最初に呼び出されるのかを理解できません。
メンテナンス用の書類の概要

ファイル分割されたファイルが幾つも(いくつも)ある場合、例えばゲームソフトだとして、ジャンルがRPGなら
メンテナンス用の書類の概要

などのようにファイルが幾つもある場合、
メンテナンス用の書類の概要

システム構造書に、
メンテナンス用の書類の概要

などのように、それらのファイルが何を処理しているのかを第三者が分かるように書いてください。また、なるべく箇条書きで書くのが、読みやすくて便利でしょう。
メンテナンス用の書類の概要

当たり前に残すべきメモのように思えるかもしれませんが、しかしこういったメモが残されてない職場は多くあります。悪い見本です。とにかく、瑣末なことでリバース・エンジニアリングを後任者にさせないように書類を残す習慣をつけましょう。
メンテナンス用の書類の概要

ダメな一般IT企業だと本当によくあるパターンで、ファイル解説の書類など何も残ってないのに自社アプリのファイルサーバーには「system.cpp」などの漠然とした名前のファイルだけがいくつもある場合が時々よくあり、「systemって何のシステムだよ・・・」と後任者があきれたくなるファイル名のプログラムがいくつもある場合、これは大変にリバース・エンジニアリングの手間を発生させる、プログラマーにとってイヤなパターンです。
メンテナンス用の書類の概要

暗黙の前提ですが、画面名やファイル名などの名前を決める際には、具体的な名前をつけるべきです。
メンテナンス用の書類の概要

書籍『ゲームプランナー入門 アイデア・企画書・仕様書の技術から就職まで』によると、ゲーム業界でもそう指導されています。
メンテナンス用の書類の概要

ゲーム業界に限らず、一般のIT業界でも同様に具体的に命名するべきでしょう。つまり、「file1.cpp」とか「a.cpp」みたいなファイル名は厳禁です。また変数名でも「b」とか「variable1」(英語でvariableとは「変数」という意味)みたいな変数名は避けてもらいたいです。
メンテナンス用の書類の概要

なお、一般企業では箇条書きの説明をするとき、よくエクセルなどの表形式で説明することもあります。
メンテナンス用の書類の概要

のような表形式でよく箇条書きが書かれます。
メンテナンス用の書類の概要

開発した原作者には、「ファイル名から予想がつくだろ?」と当然に思うことであっても、意外と、通じない場合がありますので、きちんとコード解説書に、ファイルの処理内容を文章で書くべきです。
メンテナンス用の書類の概要

例えば、RPGの「メニュー」と言われても、あなたは「道具」「装備」などの画面を思い浮かべても、ほかの人は、戦闘シーンの「戦う」「逃げる」などのコマンド画面を思い浮かべるかもしれませんし、あるいは会話イベントの「はい」「いいえ」などの返事の選択画面を思い浮かべるかもしれません。
メンテナンス用の書類の概要

また、「マップ」 map と言われても、あなたは「主人公が現在いる場所の周囲」を思い浮かべても、ほかの人は、道具「地図」を使うと画面表示される世界マップと、世界地図のなかでの、主人公のいる地方の位置を思い浮かべるかもしれません。
メンテナンス用の書類の概要

または、「洞窟などのダンジョンの構造が書かれた地図のような道具が、そのゲームの中にあるのでは?」とか想像する人もいます。
メンテナンス用の書類の概要

このほか、数学用語で「map」(日本語でいう写像(しゃぞう)のこと)という用語がありますので、それと混同される場合もあります。
メンテナンス用の書類の概要

このように、ファイル名だけだと、いろいろと想像されてしまいます。
メンテナンス用の書類の概要

なのでコード解説書を作る場合、もし仕様書側に解説が無い項目なら、そのファイルのソースコードを読まなくても理解できるように、きちんとファイル内容の要約を解説書に書きましょう。
メンテナンス用の書類の概要

このほか、どうしても「System.cpp」とかのような漠然とした名前のファイルがある場合、何のシステムなのか、わかるように書いてください。(そもそも、そういう漠然とした名前を避けたほう安全ですが。)
メンテナンス用の書類の概要

たとえばRPGを作るなら、
メンテナンス用の書類の概要

などのように、そのゲームで使うパラメーターについて、ひととおり、変数名と、その内容の要約を書いてください。
メンテナンス用の書類の概要

たとえ原作者には「当然だろ」と思えることであっても、他人には意外と通じません。
メンテナンス用の書類の概要

たとえば、「defence_power」と言われても、仮にアナタは「防御力」のことだと思っても、ある人は
メンテナンス用の書類の概要

とか、思うかもしれません。
メンテナンス用の書類の概要

また、防具の防御力と、人物の防御力とを、同じ変数にするか、違う変数にするのかどうかも、「defence_power」という名前だけでは分かりません。
メンテナンス用の書類の概要

でも「人物の防御力」というように要約があれば、「あっ、防具の防御力は、人物の防御力とは別の変数なんだな!」って分かります。
メンテナンス用の書類の概要

また、
メンテナンス用の書類の概要

のような、魔法のような非現実的なファンタジーを前提にしたパラメーターがある場合、そのパラメータが何に影響をするのか、仕様書のほかの部分に書いてください。
メンテナンス用の書類の概要

例えば、
メンテナンス用の書類の概要

上記の要約だけでは、疑問がどんどんと出てきます。
メンテナンス用の書類の概要

市販のRPGでも、「魔力」「賢さ」「精神」の数値が増えると、何に影響するかは、ゲームごとに違います。
メンテナンス用の書類の概要

つまり、
メンテナンス用の書類の概要

などのように、何によって決定されるのかを、書いてください。
メンテナンス用の書類の概要

もし要件定義書など別の書類に書いてあるなら、それを参照する形で簡略化してもいいですが、しかし要件定義書には一般に変数名(「attack_power」とか)は書かれていないので、やはり、こういうコード解説書も作っておくのが良いでしょう。
メンテナンス用の書類の概要

たとえ、コード解説書の記述が、他の書類と説明がいちぶ重複していても、かまわないでしょう。
メンテナンス用の書類の概要

むしろ、他の書類と相互に照合することにより、設計ミスなどを見つけやすくなる場合もあります。
メンテナンス用の書類の概要

とはいえ、コードのすべてを解説するのも時間的に困難なので、説明に優先順位をつけ、設計者に必要なことを優先して書くようにしましょう。
メンテナンス用の書類の概要

なお、このコード解説書を書く場合、けっして単に「どこの変数の内容がいつ、どういう内容に変わる」とかだけを書くのではなく、その作業を通して何を実現しようとしているのか等の意図も、書くようにしましょう。
メンテナンス用の書類の概要

自分の書くコード解説書でバグのある内容を記述してしまうというミスをしてしまう場合もあります。なので、万が一、そういうミスをしてしまった場合に、将来的に仕様書を読まされる後輩たちが修正しやすくするためにも、できれば各コードの意図・目的なども併記するようにしましょう。
メンテナンス用の書類の概要

たとえ執筆時点でバグは無くとも、ソフトウェアによっては将来的にOSやらミドルウェアやらの変更が必要になったりする場合もあり、そういう場合に既存の仕様では動作しなくなる場合もあるので、仕様に変更の必要が生じる場合もあります。
メンテナンス用の書類の概要

もちろん、細かいことはソースコードにコメント文で書け済みますが、しかしもしソース側でかけないような事があれば、解説書の側で書くと良いでしょう。
メンテナンス用の書類の概要

なので、そういった将来のミドルウェア変更のような事態も見越して、特に重要になりそうな各プログラムがあれば、そのプログラムの作業内容の意図・目的なども、できれば、どこかに書いておきましょう。
メンテナンス用の書類の概要

とにかく、それぞれの書類で説明が他書類と重複していて説明文がやや増えても、説明の多いぶんには、デバッグが効率化するので問題ないのです。仕様書の分野では、説明の「大は小を兼ねる」です。
メンテナンス用の書類の概要

後任者が、仕様書や「要件定義書」や「○○設計書」などの各種の書類などを読むのは、仕組みを把握したり完成目標を確認する理由のほかにも、前任者の開発の経緯やそれにともなう思考の経緯を知りたいという理由もあります。
メンテナンス用の書類の概要

たとえば、もし古いソフトに不具合が出たときなどに、設計ミスなので設計変更が必要ですが、 後任者がどこの設計部分がどういう事情でそういう設計になったかが分からないと、後任者がどう設計変更でイジレナイからです。
メンテナンス用の書類の概要

(実際には書類不足などで前任者の意図が分からない場合も多く、そのため、テストを頻繁に繰り返すことになり、工期が増えて残業なども増えてしまったりします。)なので、もしも書類がうまく残っていて、前任者の「こういう理由で、こういう設計にしました」という設計者の思考の経緯が書類に残っていれば便利です。というか、それが無いと困ります。しかし困ったことに、無い場合が多いので、日本の技術者はよく困ります。
メンテナンス用の書類の概要

設計者の思考の経緯を伝えられるような、そういう定型の書類形式というのが、ありません。「要件定義書」、各種の「○○仕様書」、「△△設計書」などを見ても、そこには通常、思考の経緯は書かれていません。
メンテナンス用の書類の概要

「要件定義書」や「○○設計書」などは無いよりかはマシで、思考の経緯などを推測するヒントにはなりますが、あくまでヒントどまりです。 「部品と機能の対応表」のようなものがあれば、かなりヒントにはなりますが、しかし、それでもヒントどまりです。
メンテナンス用の書類の概要

なお「部品と機能の対応表」の目的は、けっしてヒント目的だけでなく、設計内容のチェック用資料や他ソフトなどとの連携をする際の資料なども兼ねています。なので、たとえ思考の経緯を残した書類を書けても、「部品と機能の対応表」の種類も書類作成を省略せずに作るべきです。
メンテナンス用の書類の概要

とにかく、後任者のために書類を残すとき、思考の経緯もうまく手短かに分かるように書類も作りましょう。
メンテナンス用の書類の概要

このコード解説書のページ数は特には決まっていませんが、おおむね、持ち運びやすい程度の厚さになるページ数にしておくべきでしょう。
メンテナンス用の書類の概要

この手のメンテナス資料でよくあるトラブルが、退職エンジニアの資料紛失です。
メンテナンス用の書類の概要

会社の上司が、メンテナンス資料の定期チェックをサボりたいあまりに、担当エンジニア個々人のパソコンにだけ資料を保存させておいて、そのエンジニアが退職などしたときに資料が紛失するトラブルが日本各地で多発しています。(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない場合が多い。)退職したエンジニアの使っていたパソコンは、次の新人のためにフォーマット初期化するので、フォーマットの際にメンテナンス資料も消えてしまうというトラブルです。
メンテナンス用の書類の概要

「会社の共有フォルダにメンテ資料を置きましょう」と提案しようにも、しかし上司のチェックすらされてない資料が共有フォルダに置かれるわけもないので、結局はそういう会社ではエンジニア個人のパソコンでメンテ資料を管理させられたりもします。そして、いつしかメンテ資料が消失しています。
メンテナンス用の書類の概要

この手の資料消失のトラブルを未然防止する簡単な方法は、定期的に、部署の部長課長などや上司などの管理者が、現場エンジニアから上がってきたメンテナンス資料の原稿を、(管理者が)定期的にチェックする必要があります。
メンテナンス用の書類の概要

また、こうやって定期チェックすれば、万が一、メンテ資料消失しても、資料を普段から検査してきた上司や検査担当者の頭の中に記憶が残っているので、ノウハウの復旧が比較的に容易です。
メンテナンス用の書類の概要

しかし、部長や課長などが原稿チェックを面倒くさがっていると、上述のようなトラブルになります。
メンテナンス用の書類の概要

どこの技術系の企業でも、設計図のチェックは念入りに行いますが、しかしメンテナンス用資料のチェックが省略されたりする会社が多くあります。 資料紛失は会社側の自業自得でもあります。
メンテナンス用の書類の概要

なお、上司がチェックを面倒くさがっているという理由でメンテ資料が個人管理されている場合、当然、その資料は印刷などはされていません(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない)
メンテナンス用の書類の概要

なので、退職しなくても、ハードディスク故障などが起きればメンテ資料は消失して一巻の終わりです。
メンテナンス用の書類の概要

退職が決まったときに会社は引継ぎ資料をエンジニアに作成させようとしますが、当然、上述のような技術資料が急に作れるわけもなく、そもそも資料の内容が上司や同格の技術力のエンジニアから検証チェックもされてないので信頼性も不明だし、よって急ごしらえの資料作成は大抵、失敗に終わります。
メンテナンス用の書類の概要

根本的な原因は、メンテ資料のための作成費用を普段から出していなかった会社の態度です。また、この手の会社は、そもそも論として、退職エンジニアより昔の前任者からのメンテ資料すら用意していないのが通例です。そんな杜撰(ずさん)な管理体制なので、大抵の企業では、急ごしらえのメンテ資料の作成は失敗します。会社の自業自得です。
メンテナンス用の書類の概要

つまり資料消失であわてる会社というのは、そもそも、まともにメンテ資料の上司によるチェックもしていなかったという会社であり、いろいろと自業自得です。
「単位動作」という概念

主に機械工学教育の用語なのですが、「単位動作」という用語があります。
「単位動作」という概念

たとえば、熟練工の動作は、一見すると色んなスキルを習得しているので複雑に見えますが、しかし動作のひとつひとつは、たとえば卓上ボール盤なら教科書どおりの卓上ボール盤の使い方ですし、やすりがけ の動作も、教科書どおりの動作です。
「単位動作」という概念

複雑な動作も、教科書どおりの動作を、組み合わせただけに過ぎません。
「単位動作」という概念

そして、その やすりがけ だけの動作の説明も、図や写真などを使って、「手順1:○○をする。」、「手順2:△△をする。」などと一段階ずつ、1ステップも抜かりなく 教えます。
「単位動作」という概念

だから、工業高校や大学の機械工作実習では、教科書どおりの動作をひとつずつ、教えます。
「単位動作」という概念

けっして、いっぺんにまとめて、別種の動作を教えません。
「単位動作」という概念

このように、動作をひとつひとつの単純な動作に分解することを単位動作といいます。
「単位動作」という概念

なぜ、わざわざこんな事を説明するかというと、世間では複雑な物事を説明するときなのに、いっぺんに教えたがる人がいます。しかし、そういう教え方は、多くの開発現場ではNG(エヌジー、ノー・グッド)です。
「単位動作」という概念

残念なことに、インターネット上には、一見すると説明書の文章量が多くても、実態を読むと、このような作者以外でないと操作方法を読み解けないようなダメな説明法をされているツールも、残念ながらネットに多く公開されてしまっています。
「単位動作」という概念

単位動作を意識した解説の書き方は、べつに難しくなく、普通に、 たとえばwindowsのオフィスソフトなどのヘルプファイルや、あるいはオフィスソフトについての市販の操作解説書のように、 「~~をしたい」といった操作目的の種類ごとに一個ずつ手順を段階的に教えればよいだけです。
「単位動作」という概念

単位動作の説明を軽んじる人が根本的に勘違いしていることは、「複雑な動作を練習したほうが、スキルが上達する」という勘違いです。
「単位動作」という概念

むしろ物理学の公式のように、単純で短いものに置き換えたほうが、物事を考える際の部品として使いやすくなるのです。 だから実際の順序は、「単純な動作を見つけ出すために、その何倍もの練習や試作をする」のです。たとえるなら、発明家の努力のようなものです。「99%の努力の上での、1%のひらめき」です。
実社会のデータベースでは過去データは消さない

在庫管理ソフトで、もし在庫部品データで、購入元メーカーで生産中止になったりした部品があっても、一切、在庫データベースからは登録を消しません。
実社会のデータベースでは過去データは消さない

もし消したりすると、次の登録番号の部品との登録情報の連続性が無くなり、登録データが飛び飛びになるので、大変に管理が難しくなるからです。
実社会のデータベースでは過去データは消さない

だからともかく、生産中止部品のデータベース管理では普通、その部品の末尾コメントに「生産中止」などと書き足すだけにして、登録そのものは維持します。
実社会のデータベースでは過去データは消さない

また、自分が使っていなくても、過去の自社製品を購入した客先がその部品を組み込まれた自社製品を使っている場合もありますので、残す必要があります。
実社会のデータベースでは過去データは消さない

だからもし、生産中止でなく単に入力ミスなどで登録済みの部品をまた登録してしまったことが判明した場合も、 最新の登録IDでない限りは、消すのではなく、末尾コメントに「登録ミス。すでにID○番で登録済み。」のような記録を書いて残したままにするのです。
実社会のデータベースでは過去データは消さない

こういうのはデータベースを運用する際の基本テクニックです。
実社会のデータベースでは過去データは消さない

製造業の図面などの「部品表」の番号でも、同じようなテクニックが使われます。設計変更により過去の廃止になった部品に当てられていた番号は、消すのではなく、新規の番号を確保して、その新規番号に代替の新部品を割り当てるというテクニックです。
実社会のデータベースでは過去データは消さない

また、「登録IDを最整列して並び替える」なんてことは、一切、しません。そもそも、在庫ソフトにそのような機能も原則、ありません。
実社会のデータベースでは過去データは消さない

なぜなら、すでに紙に印刷した実物の台帳に保管されている登録ID番号までを、在庫管理ソフトで書き換えることは不可能だからです。
実社会のデータベースでは過去データは消さない

一般に在庫の台帳は小さな事業所でも数千種類の在庫部品があるので、台帳にあるその数千種の再チェックをするのは時間の無駄なので、並び替えはしません。もし在庫番号の並び替えをすると、「本当に並び替え後の番号が合っているか?」などのチェックの手間が生じます。
品質の検証

製造業でもIT企業でも品質の検証は、部品ごとの検証と、全体の組立てをしたあとの検証という、最低でも2段階です。
品質の検証

少なくとも、自動車業界はそうです。
品質の検証

個々の材料部品などは、実際に引張り試験や荷重試験などを実際に物理実験を行い、部品の耐久値が規定や要求仕様を満たしているかを、事前に確認します。そして自動車の走行試験や衝突試験などは、実際に部品を組み立てて製品の状態である自動車にしてから走らせて見るしか、方法はありません。
品質の検証

チェックにおいて、シミュレーションなどは無駄です。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もありません。
品質の検証

「チェックの最終確認においてシミュレーションが無駄」といのは、これは自動車業界だけでなく、航空宇宙などでも同様です。日本のJAXAは「はやぶさ」の部品モジュールの開発において、実際に部品を組み立てたうえでの(シミュレーションではなく)物理実験をしています(※ 講談社ブルーバックス『小惑星探査機「はやぶさ」の超技術』で確認できます。)。
品質の検証

また、産業技術総合研究所での測定の国家標準器開発などでも同様の手法であり、実際に測定器を製品として組み立てた上での物理実験をしています(テレビ番組では、TBS科学番組『夢の扉』でメタンハイドレート採掘の産総研の研究者が、そうシミュレーションの問題点を指摘しました)。
品質の検証

ソフトウェアの開発では原理的に物理実験は無理ですが、それでも不具合対策の確認は、最終的には、実際にそのソフトをユーザー視点で使用してみる「実践」/「試用」しかありません。
品質の検証

ソフトウェア業界だと、個々の部品ごとにチェックすることを「単体テスト」といいます。一方、全体的に組みたててみてチェックすることを「ビッグバンテスト」と言います。
品質の検証

さて、チェックにおいて、シミュレーションなどは無駄であり。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もないのでした。
品質の検証

ではシミュレーションの意義は何かと言うと、工業系に強いライター(「文筆家」の意味)の山根一眞『メタルカラー』シリーズのどれかに書かれていると思いますが、意義はけっして直接のチェックではなく、既に行った物理的な検証実験をもとにそれをシミュレーションと照らし合わせることにより相互検証することで、検証回数を減らすことにより費用節約するのが目的です。
品質の検証

たとえばシミュレーションなしでは20台の機械装置を耐久実験のため壊さないといけない工程であると仮定して、もしシミュレーションありなら耐久試験で壊すのは12台ですむ工程にできるなら、今後の自社の新製品では8台ぶんの費用が節約できます。そういうコストダウン投資のためにシミュレーションをするのです。
品質テスト

ソフトウェアのテストは、IT企業では、よく新人がやらされる仕事でもあります。新人研修に組み込まれていたり、研修明けによく与えられる仕事でもあります。
品質テスト

なぜなら、自社ソフトウェアの内部構造の知識が乏しくてもテスト自体は可能だからです。
品質テスト

製造業などでも、多品種少量生産の設備機械そのものの生産では、たとえば簡易的な耐久試験などのために「実機のボタンAを押した後に画面遷移後にボタンBを押すのを、50回繰り返す」みたいな簡易的かつ長めの時間の繰り返しテストは、よく新人の仕事です。(なお、50000回の繰り返しみたいにテストが長すぎると人間じゃ無理だし(機械で繰り返すことになる)製品が磨耗して壊れたり製品寿命が大幅に減るので、せいぜい人間でも可能な500回くらいまでにとどめて、人間がテストしたりします。)
品質テスト

どの業界でも、テストのうち、時間の掛かる繰り返し試験は、よく新人に与えられる仕事です。
品質テスト

いちおう、設備機械の組立て直後の段階で、「ボタンAを1回だけ押すテスト。ボタンBを1回だけ押すテスト。」みたいな(繰り返しでない)短時間テストは、機械を組み立てした生産者本人が現場で行います。しかし、「500回繰り返す」みたいな仕事は長いので、新人がテスターを行うのがよくある会社風景です。
オーバーエンジニアリングを避ける

「オーバーエンジニアリング」(over engineering)という用語があり、善かれと思ってもか、余計な設計をしてしまう事です。」
オーバーエンジニアリングを避ける

たとえばソフトウェアの設計の場合、あらゆるバグを想定して個別に対応したコードを書こうようとしてしまうと、コードが長大になってしまい、保守性がいちじるしく低下してしまいます。
オーバーエンジニアリングを避ける

システムのあらゆる部分にバックアップを持つのも、時間的にも費用的にも不可能であり、オーバーエンジニアリングです。
オーバーエンジニアリングを避ける

製品と寸分も違わぬデザインパターンを追求しようとして、ろくに実装もしないのもあります。また、そのような発想で書かれたマニュアルは、膨大な学習コストが必要であり、実用性が乏しいです。
オーバーエンジニアリングを避ける

最小限の機能だけのプロトタイプを作る手法です。
オーバーエンジニアリングを避ける

生命などの安全にかかわるものでもないかぎり、失敗を許容しましょう。
オーバーエンジニアリングを避ける

機能が実際に必要になるまで追加しない方法です。
オーバーエンジニアリングを避ける

ソフトウェアの場合、あとからでも比較的に容易に追加できることが多いので、こっちのほうが良いでしょう。
オーバーエンジニアリングを避ける

ただし、航空宇宙や造船などは別かもしれません。
工学では現状、「設計図とは何か?」といった理論は存在しません。情報工学でも、「IT企業の仕様書をどう書くか?」という書籍は、ほとんどありません。大学生向けの情報工学の参考書でも、まず触れられてない分野です。
本ページでは現状では参照していない文献ですが(2022年2月11日)、設計の理論を紹介していると思われる関連文献として『岩波講座 現代工学の基礎』があります。ある程度、設計についての抽象的な説明があるかもしれません(たとえば『岩波講座 現代工学の基礎〈1〉設計の方法論』(2000/5/10)あたり)。 しかし岩波のこの本はそんなに厚くないし、ソフトウェアも含めては説明していなかったかもしれません(手元にないので確認できません)。
ITの場合、ビルド手順の記録が必要

集団でソフトウェアを作るとき、そのソフトウェアのビルド方法を仕様書に書かないといけません。(これは製造業の設計図などには無い、IT業界の独自の事情です。)
ITの場合、ビルド手順の記録が必要

ビルドとは、実行ファイルを作ることです。
ITの場合、ビルド手順の記録が必要

Visual Studio などのソフトウェア開発環境ツールは大抵、ビルド機能もあるので、最低限、作者が実際に使用した開発ツールを書いておく必要があります。ビルドに必要としたソフトウェア(ビルド実行ソフトや、必要なライブラリ)、ビルドのためのコマンドや操作手順なども、ひとつひとつ詳細に書くべきです。
ITの場合、ビルド手順の記録が必要

実際に自分がそれらビルド手順のとおりにソフトウェアだけをインストールと設定を試してみて、もしその手順の指定に従えば(従うのが知識的に簡単かどうかはともかく)、とりあえずビルドできて、実行ファイルを生成できる程度には、書く必要があります。
ITの場合、ビルド手順の記録が必要

ソースコード公開サイトなどのプログラムを見ると、説明書を見てもどこにもビルド方法や実行環境が書かれておらず、ビルドできずに使いようのないコードが時々あります。ビルド不可能ではあまり有意義なソースとは言えないでしょう。
必要な書類

一般のIT業界や製造業の場合、集団作業で必要となる書類は、主に下記のセットでしょう(編集者Sの推測)。
必要な書類

設計図とは完成図のことです。
必要な書類

さて、一般のIT企業や製造業では上記の設計図~参考資料に加え、必要に応じて「説明書」、などを加える場合もあります(業界や会社によっては、説明書は上記セットとは別の本棚などに分離する場合もある)。この4〜5点セットの書類を、集団作業の便宜のために、将来にわたって残していきます。(土建や製造業などの堅い業界の場合は、「設計図書」(せっけい としょ)、などの名前で管理されることもあります)
必要な書類

娯楽産業ではない一般のIT企業や製造業でも、製品の企画に至った経緯を記した書類を、大元のアイデアを考えた会社の側では残しています。(ただし一般企業の場合、社内プレゼン用資料の流用の場合もある)。上記セット一覧のうちの「設計図」はゲーム業界では「仕様書」に対応しており、「企画に至った経緯を示した書類」は「企画書」に対応しています。一般企業では書類の名前は、「企画書」ではない場合も多く、業界や会社によって異なります。
必要な書類

企画書だけでなく、マトモな科学論文とかでも、既存品と今回の製品とはどう違うのかという構成が好まれます。つまり、論文なら「何を新発見したのか? → いままでの理論ではどうだったか?それと今回の新発見とでは何が違うか? → 発見のプロセスや詳細など」といった構成が、マトモな科学論文のあるべき構成です。
必要な書類

また、メンテナンスのための図面として、「フロー図」とか「モジュール図」や「システム図」等、設計図としての目的でない将来的なメンテナンス改修などを見越して作成される図を、保存しておく必要があります。
必要な書類

一般IT業界の仕様書の書き方の本やwebサイトを見ると、「要件定義書」「内部設計書」「外部設計書」「ネットワーク図」「業務フロー図」「インターフェース設計書」「モジュール設計書」などの色々な書類・図面がありますが、発注元で最低限必要なのは上記4点セット(完成予想図、メンテ用資料、企画書類、外部資料)でしょう。IT業界特有の設計書類も、完成予想図またはメンテ用資料を作成するため手段に過ぎません。
「設計図」とは完成図である

では「設計図」とは何かというと、製造業の場合での「設計図」の意味を説明すると、それは「完成予想図」です。「完成予想図」というところがポイントで、実は生産方法などは指定していないのです。なので設計図だけでは、実は何も生産できないのです。
「設計図」とは完成図である

なので設計図に加えて、現場で必要な生産方法の技術をもった技術者が、さらに必要です。なので、設計図はあくまで、最低限必要な情報でしかないのです。実際には、設計図以外にも、生産方法についてのさまざまな情報が必要です。
「設計図」とは完成図である

ですが、どこの業界でも、生産方法については図面化しないか、たとえノウハウを部分的に文書化していても社外秘にしていて非公表なのが通常です。
「設計図」とは完成図である

IT業界でも、あるソフト製品のプログラミングの具体的なノウハウについては、その製品の「仕様書」には記載されないのが通常です。
「設計図」とは完成図である

完成予想図として「部品図として、このような寸法(各部の長さ)・形状・材料をもった部品を図面の指定どおりに作れば、あとは組立図に部品どうしの相互位置が書いてあるので、(組立図の)その位置指定とおりに取り付ければ、必ず完成しますよ」
「設計図」とは完成図である

という状態にまで、部品図と組立図の状態をそれぞれ完成予想図の形で書き上げていくのが、図面を書くという事です。
「設計図」とは完成図である

技術的の企業でいう「設計図」の意味は、おおむね、こういう意味です。
「設計図」とは完成図である

もし、納品される品物が仕様を満たしてない場合、けっして合格品としてはいけず(つまり「検収」してはいけず)、(発注者は)協力会社に作り直しを要求します。この仕様違反のさいの作り直し要求はIT業界にかぎらず製造業でもどこでも、受け入れ検査は通常、そういう仕組みです。
「設計図」とは完成図である

ソフトウェアを作る場合も、最終的に製品の完成の段階では、最低限このような水準にまで、設計図を作りこんでいきましょう。(ただし、ソフトウェアには「寸法」など形状の条件は無いので、そこはアルゴリズム的な条件に意味を読み替えること。)
「設計図」とは完成図である

製造業では図面をもとに見積もりをします。基本的に技術系の業界では、設計図をもとに見積もりが行われるます。
「設計図」とは完成図である

学生は企業社会を知らないと思うので説明しますが、コンピュータ業界にかぎらず、そもそも製造業なども含む技術系の業界で、設計から生産までの流れがどういう工程で行われているか、説明します。
「設計図」とは完成図である

まず、なにかの設計図では、具体的な生産方法は指示しません。たとえば、組み立てた後の形状がどうなってるかは組立図(くみたてず)に描いても、しかし、「どうやれば組み立てられるか?」とかの情報は一切、そういう事については『設計図』では指示しません。
「設計図」とは完成図である

ともかく、なにかの設計図は通常、その製品の完成図である必要があります。製造業で「図面」と呼ばれているものは、こういった具体的な完成予想図のことです。
「設計図」とは完成図である

そして、その完成図はいくつもの部品から成り立っているのが普通なので、完成品をいくつかモジュールごとに分解した部品図(ぶひんず)をいくつも作成して、それぞれの作成担当の作業者に渡します。
「設計図」とは完成図である

こうすることで、分業もしやすくなり、一石二鳥です。
「設計図」とは完成図である

基本としては、設計図とは、設計図だけを見ても、あいまいさの無い状態で完成品の満たすべき具体的な条件が分かるようにしなければなりません。
「設計図」とは完成図である

さて、製造業などでも、「図面」という完成予想図があります。
「設計図」とは完成図である

よく、IT業界でいう「現場で見つかった仕様書の不具合を仕様書にフィードバックする」とか言う表現は、おそらく完成予想図のような書類のことを指していると思います。
「設計図」とは完成図である

なぜなら製造業でもフィードバックは図面に対して行います。なので、製造中に不具合が見つかれば、どんどんと図面が改訂されてゆくし、そのために設計者は現場に立ち会うし、場合によっては設計者みずからが製造もしていきます。
「設計図」とは完成図である

技術系の業界では一般に、書類で作業指示を出すときに、いちいち、けっして具体的に、「作業員であるアナタは、○○のコンピュータの△△ボタンを押して、××をしてください」のような指示は出さないです。
「設計図」とは完成図である

指示はそう出すのではなく、図面のような完成予想図(ただし決定稿)を出して、「この完成予想図のとおりになるように作っておいてください。」というような指示が出ます。
「設計図」とは完成図である

さて、IT業界の場合、末端の部品プログラム完成予想図を描く前に、普通の設計では既にフローチャート図または状態遷移図などといった、全体的なシステムの図面を書くのが望ましいとされています。(以降の説明では、言い回しの省略のため、フローチャート図または状態遷移図を単に『フロー図』または『フローチャート図』と略記する。)
「設計図」とは完成図である

なので、もし横断的な説明をしたければ、このフローチャート図を作るとき、このフローチャート側に説明を追加するとか、あるいは、フローチャート図を参照する形で別途の参考図を追加するとかすれば、良いかもしれません。
「設計図」とは完成図である

こうすれば、もし末端部品プログラムを訂正することになっても、訂正の必要のある図面は、末端プログラム図面と、その直接の上流のフロー図あるいはフロー別途参考図だけのたった2枚に限定できますので、訂正の手間を減らせるので効率的です。
「設計図」とは完成図である

なお、もしかしたらIT業界でも、状態遷移図やフローチャートを描かないで設計する事態も企業によっては横行しているかもしれませんが(原理的には、状態遷移図やフローチャート図が無くても、エクセルなどで作成した部品プログラム仕様とその組み立て仕様のエクセル形式の完成予想図だけでも、原理的にはソフト設計できてしまう)、しかし、こういう状態遷移図などの画像での説明を省いた設計では設計ミスが発生しやすく、結局、再設計などの手間が掛かってしまうのがオチです。
「設計図」とは完成図である

なお、一枚の仕様書の中では、内容の重複はオッケーです。
「設計図」とは完成図である

たとえば、機能の似たモノを2個つくるとき、
「設計図」とは完成図である

2個目の説明では、「○○については△△と同じ」のように、「~~~と同じ」というふうに説明できるから、です。製造業でも、一枚の図面に正面図と側面図の2方向の図のある場合、側面図に参照値として正面図の値を書くと、正面図の設計変更にともない、ときどき側面図にある参照値を修正し忘れるミスがあります。)
「設計図」とは完成図である

なので、よほど仕組みの複雑な難しい製品でないかぎり、なるべく2回目以降の説明では具体的内容は書かないのでおくのが、設計の図面では修正モレを防げるので安全です。
「設計図」とは完成図である

ただし、これはあくまで、設計図面の書き方です。教本や指導書などの書き方とは、設計図面の書き方は、違います。もし、新人むけの指導書や教科書・教本を書く場合には、やや重複のある内容でも何度も説明して覚えさせましょう。
要求事項書

要求事項は、「○○してもらいたい」という指定も必要ですが、ソレとは別に、できれば、「なんの目的で、そういう指定をしているか?」などの理由も書いてあると、ニュアンスが正確に伝わるので、伝達ミスなども減ります。
要求事項書

企業秘密などで無いかぎり、できるだけ、目的も平気したほうが良いでしょう。
要求事項書

要求事項の書類には、要求には理由も併記するのが望ましいと指導されているようです。
要求事項書

さて、一般IT企業で要求事項書の話題に戻るとして、また、意外と伝達側が設計ミスをする場合もあるので、目的も書面で伝えておくことにより、相手先の人が、気を聞かして検証してくれます(べつにボランティアで検証してくれるわけではなく、どっちみち相手先が設計中に結果的に検証することになるで、だったら要求事項に目的も書いておいたほうが効率的になる)。
要求事項書

なんども指摘するが、「要求事項」だの「設計図」だの何種類も作る書類セットの書き方では、説明が重なって多いぶんには問題ないのです。(ただし、要点などを抜き出した簡略版の説明も必要。)
要求事項書

大は小を兼ねます。
要求事項書

なお、社会人の情報伝達では、結論を先に言うのがマナーなので(詳しくは『中学校国語/現代文/報告書の書き方』)、要求を先に伝えてから、理由を直後に伝えます。つまり、文章のテンプレートとしては、
要求事項書

のような順番になります。
要求事項書

設計図の各書類は一般的に外部には非公開なので、書類セットくらいでしか体系的な説明をできないので、むしろ別書類にて説明の重複などがあって相互検証できるくらいのほうが、安全なのです。なお、要求事項の段階では、あまり細かく事項書を作りすぎずに、そのぶん実際のプログラムの開発を早めましょう。
データ台帳

重要なことは、一般のソフトウェア開発などでの実務では、なんらかの特殊な数値データが組み込まれている場合、台帳と実物プログラムとによってダブルチェックをするという事です。(ゲームだけでなく、製造業の組み込みソフト開発などでも、台帳などによってダブルチェックをしています。)
データ台帳

IT業界では、ダブルチェックを軽視している人が多いですが(たとえば電卓とパソコンソフトとの計算結果のダブルチェックを批判する言説がネットに多い)、そういうのは製造業や組み込み業界などでの実務を知らない知ったかぶりのタワゴトなので無視しましょう。
データ台帳

マトモな業界では、プログラムの検証のため、そのソフト以外およびそのソフトを動かしているハードウェアとは別のデバイス(電卓でも良い)を使って、ダブルチェックをするのが常識です。(※この常識には出典を出せませんが(企業秘密などに関わるので)、しかしダブルチェックを軽視する側の主張も満足な出典を出せていないので、対抗的にこの文を残します。)
データ台帳

さて、入力されたハズのデータの台帳のような内容の一覧の書類が、一般の技術系企業では必要です。業界で「台帳」と言うのかは知りません。名前が無いと困るので、とりあえず土木工学ではこういうのを「○○台帳」というので、それに習って「データ台帳」という題名を本セクションでは、つけているだけです。なので、IT企業では別の呼び名かもしれません。
多項式近似

測定値などで、入力変数が一変数なら、エクセルなどを用いて多項式近似が出来ます。
多項式近似

一般にIT業界での実務の多項式近似では、原理的には9次でも20次でも、どんなに次数が高くても(おそらく int 整数型の限界くらいまで)計算できてしまいますが、
多項式近似

しかしIT業界などの実務では人間の検算などの手間を減らすために、なるべく、せいぜい2次式や3次式といった、低めの次数におさえて利用するのが、IT企業では普通です。
多項式近似

もし先端科学のための多項式近似なら、9次を超えるような多項式近似をするような場合もありますが、しかし、一般の企業では、そこまでの多項式近似は不要ですし、むしろ検算などの管理の手間が増えるので、9次のような多すぎる次数は嫌われますので、なるべく2次ていどに抑えましょう。
バグあると人の死ぬ業界

ゲームではバグがあっても、人は死にません(過労自殺などを除けば)。なので、アイデアが思いついたら、どんどんとプロトタイプで試してみましょう。
バグあると人の死ぬ業界

ですが、他の業界だと、バグがあると人が死ぬ場合もあります。たとえば、製造業での、組み込み機器などがそうです。
バグあると人の死ぬ業界

書籍で紹介されている事例だと『メタルカラーの時代』シリーズ(山根一眞(やまね かずま)による取材)で、 「日本ユニシス」というIT企業がかつて、提携している別企業のNC工作機械に向けた組み込みソフトの開発で(組み込みソフト部分をユニシスが開発)、開発テスト中のバグにより工作機械の刃物が本体にぶつかって折れて飛んできて、あやうく人が死ぬところだった、 ・・・という感じの事例がインタビュー先のプログラマから紹介されています。 それまで日本ユニシスおよびその担当プログラマーでは、組み込みの仕事はほとんど扱わずに、どちらかというとIT業界内での顧客を仕事をしていたので、そういう人が死にそうな事例に経験することがなかったので、製造業の組み込みソフトでは特にバグおよびバグ予防に対する考えをIT業界内の仕事とは変えなければならない必要があることに気づかされた、とユニシスの技術者はインタビューで述懐しています。
履歴の管理

一般のIT企業でいう仕事の「仕様書」では、開発前の段階で書いた要件定義書や設計図(完成予想図)やコード解説書など」を、ソフト完成後にも残す必要があります。
履歴の管理

なぜなら、開発前~開発中の経緯を、上司や他部署に事後的に報告したり、のちに入社してくる後輩などに教育としてソフト開発時の出来事を教えるためです。
履歴の管理

このため、こういった仕事の書類には、著者や、著作・改訂の日時(「改訂日: 2018年8月30日」)や改訂者(「改訂者: 山田太郎」)などの履歴(りれき)も記載する必要もあります。
履歴の管理

のようになります。(企業では、こういうページのパソコンでの文書管理は、エクセルなどの表形式データになってるのが普通。)
履歴の管理

さらに改訂の際には、それぞれの版の改訂内容の要約を書く必要すら、あります。
履歴の管理

アマチュアの場合なら、『メモ帳』アプリなどで説明する場合もあるかもしれないので、たとえば
履歴の管理

のようにアレンジする必要があるかもしれません。
履歴の管理

アマチュアのゲーム製作の場合、エクセルまでは不要でしょう。
ファイル名の冒頭番号

ゲームを例に説明します。
ファイル名の冒頭番号

ゲーム産業に限ったことではないのですが、企業でのパソコン内での、ファイル名やフォルダ名の管理手法として、たとえば何かの説明書きのファイルがいくつもある場合、
ファイル名の冒頭番号

などのように番号順をつけて命名することもあります。「01_キャラクター設定」でひとつのフォルダ名です。なぜこのように番号を冒頭につけるかというと、もしパソコン上で名前順に並び替えたときに、必ず狙った順番どおりにさせるためです。
ファイル名の冒頭番号

そして、たとえば「キャラクター設定」フォルダ内に、さらに
ファイル名の冒頭番号

のように、さらに 番号づけの設定があることもあります。
ファイル名の冒頭番号

たとえば、「ゴンザレス」というキャラが主人公のゲームの場合、彼が最初に来てもらわないと困るわけです。もし番号が冒頭に無いと、「ゴンザレス」よりも「アルベルト」のほうが五十音順では先に来てしまいます。
ファイル名の冒頭番号

しかし、上記のように番号を冒頭につける方式を採用することで、あとでどんな名前の新キャラクターを追加しようが、必ずファイル検索の名前順検索では「ゴンザレス」が最初に来るようになるのです。
ファイル名の冒頭番号

なお、業務用のファイルでは一般的に、冒頭番号と項目名とが別々のものであることを強調するために、半角スペースを使わずにアンダーバー「_」を使うのが一般的です。
ファイル名の冒頭番号

IT企業に限らず製造業でも、たとえば図面ファイルでは
ファイル名の冒頭番号

などと、冒頭番号ごと名前をつけてフォルダ管理するのが一般的です。
ファイル名の冒頭番号

フリーソフトのファイル構成などでも、本ページはゲーム教科書なのでゲームに置き換えて説明しますが、
ファイル名の冒頭番号

のようなファイル構成のフリーソフトも時々、見かけます。
説明書

フリーゲームなどは、あまり説明書が細かくかかれないので、気にする必要はないでしょうが、一般IT企業のソフトウェア説明書や製造業の組み込みソフトなどは、もっと細かく一通りの操作方法を説明します。
説明書

イメージしやすさの都合で本ページでは、製造業などの組み込みソフトを例に、説明書の書き方を説明します。
説明書

なんと、組み込みソフトの説明書を書くためには、操作テストが必要です。
説明書

だから例えば工場の生産ライン用の設備に組み込まれてる組み込みソフトの説明書なら、その説明書の文面は、工場で下書きしてるわけです。
説明書

オフィスで下書きするのではなく、工場で下書きするのです。なので、工場にノートブック(文房具)と筆記用具(要・赤ペン)を持ち込んで、そこで説明書の文面を下書きするわけです。
説明書

たいていの新人は、実機での操作テストに気が引けがちです。
説明書

実機で操作テストばかりしてると「周囲の先輩から『この新人は書類も読まずに実機をいじって遊んでる』と周囲に見られるんじゃないか?」と不安になったりとかして、実機によるテストを遠慮しがちです。また、仕様書は読んでて勉強になりますので、ついつい仕様書ばかり読みがちで、テストを遠慮しがちです。
説明書

しかし、それは新人特有のよくある勘違いなのです。説明書を書く場合にも、実機でテストプレイをするべきなのです。
説明書

なので、下書きが終わったら、さっさと実機テストをするべきなのです。
説明書

まず、仕様書などをもとに、説明書の大まかな章や節などの構成を、仮決めします。
説明書

大まかなページ数などの仮決めのために、仕方なく仕様書を見ながら、仕様書から想定されるハズの操作方法を書きます。
説明書

この下書きは、これはこれで必要であり、あとの操作テスト時にチェックすべき項目を示したチェックリスト的な意味合いもあるので、とりあえず、実機プレイなしですが下書きをします。
説明書

ですが、この想定した操作方法は、まだ何のテストもしてないので、高確率でミスが含まれています。
説明書

なので、下書きした説明書のプロトタイプと筆記用具(赤ペン)を持ちながら、実機のある現場に移動して、到着したら実機で説明書どおりにテストプレイしながら(絶対に説明書を見ながら、杓子定規に説明書どおりにプレイします)、実機操作中に発見した説明書のミスを、赤ペンで下書き説明書に、追記でメモ書きしていくワケです。
説明書

このように仕様書ばかり読んでないで、さっさとテストします。
説明書

だから、説明書を書くオフィスは、そういうテストが気軽にできる環境の近くに存在する必要があります。
説明書

また、組み込みソフトの説明書を書く技術者は、工場の組み込みソフトを書くなら、技術書の服装としてはブルーカラーの作業着で仕事してるわけです(背広ではないです)。作業着でないと原則、現場に入れないので
説明書

組み込みソフトは、機械などに組み込まれてるわけですから、安全が確保されていて可能な限り、仮想化などではなく、実機でテストします。 (仮想化でテストすると二度手間になります。なので可能なら最初から実機でテストしたほうが早いです。)
説明書

このような仕事を、よく新人がやらされます。
説明書

新人は消費者目線に近いので、どこの業界でも、新人がよくテスターにさせられることが多いのです。
説明書

同様の理由(消費者目線)で、説明書を書く仕事も、どこの業界でも、新人がよく説明書を書かされます。
説明書

子供向けの玩具で電子玩具の説明書などだと、場合によっては説明書の文面が子供口調(「~だよっ!」とか「~だね!」みたいな口調)で説明が書かれていたりしますが、けっして説明書を書くお仕事が子供の学校の図工みたいな作り方をしてるワケではないでしょうし、おそらくは実際の執筆手順は上記の組み込みソフトの説明書のような感じの手順で説明書を書いていってると思われます。説明書の口調という表面にダマされないようにしましょう。
説明書

ああいう子供口調やら女口調の説明書は、集団作業の場合なら、下書きの段階での口調は、普通のビジネスマン的な書類の口調で書いているか、たとえ くだけた下書きの場合でも普通の大人のくだけた口調で下書きを書いているのであって、あとの工程で口調だけ入れ替えて子供口調や女口調に入れ替えるという手間を掛けていると思われます。けっしてイキナリ、子供口調とかで書類を書きはじめるわけではありません。
パラメータ調整の理論

たとえば機械設計の業界で昔から言われている教訓として(なるべく新規設計では)「材料と構造を同時に変えるな」というのがあり、日経クロステックのwebサイトでもそう紹介されています。引用元の日経クロステックの記事では「2つ以上のものを同時に変更するときは、組み合わせによる問題が起こりやすいことを示唆している」と指摘されています。
メンテナンス用の書類の概要

完成形をつくるだけの「設計図」的な「仕様書」だけでは、バグ発生時や設計ミス発生時などのさいの修理が不可能です。
メンテナンス用の書類の概要

また、ITソフトウェアなら、移植などの際に、もしソースコードだけしかなくて書類不足だと、「コードがどのように動いているのか?」を後任の人が把握できずに、移植困難になってしまうトラブルもあります。
メンテナンス用の書類の概要

前任者が会社を辞めてしまっている場合などもあるので、色々と書類が必要でしょう。こういうことから、もし下記のような資料が無いと、不具合の発生時に、修理のための設計変更で、どこをどうイジればいいか特定できず、困ります。
メンテナンス用の書類の概要

というか、残念ながらこういう資料の不足している職場は多く、なので日本のIT技術者は困っています。
メンテナンス用の書類の概要

上記書類のうち、特に「部品と機能の対応表」、「コード解説書」は、メンテナンス目的以外にも、設計図のチェックにも利用される。なので、そういう目的もあるので、ぜひ作成しておくのが望ましい。
メンテナンス用の書類の概要

「部品と機能の対応表」のことを、IT業界で何と言うのか、このページの著者は知りません。しかし、ともかくそういう対応表がないと、メンテナンスが後々に困難になります。
メンテナンス用の書類の概要

発売後の(一般のIT企業では)ソフトにも、修理・メンテナンスが不可能になる場合があります。
メンテナンス用の書類の概要

そのため、製造業などの組み込みソフトなど、まともなIT業務では、ソースコードの内部構造・全体構造のコード解説書とでも言うべき書類があることが望ましいです。(特に名前は決まっていない。また、中小企業などでは作成しない場合もある)
メンテナンス用の書類の概要

一般のIT企業では「内部設計書」や「プログラム設計書」などの名前の場合もありますが、しかし既に設計図などで大まかな指定はできていますので、設計の時点では、これらの「設計書」が不要な場合も多くあります。
メンテナンス用の書類の概要

これらの書類の目的は、どちらかというと、設計よりも、後日に読み返したときのメモ書きです。主要な変数、主要な関数などは、第三者が、なんのドキュメントも無い状態でその意図を読み取るのは、なかなか手間が掛かります。なお、最終製品やあるいはコードだけから逆に設計書や設計図などを書き起こすことを「リバース・エンジニアリング」と言います。リバース・エンジニアリングは、本来なら、後任者などには、させるべきではないのです。
メンテナンス用の書類の概要

大目的として、完成後のメンテナンスなどの際に、リバース・エンジニアリングという手間のとても掛かる作業を、けっして後任者にしないでも済むように書類を残すのが、正しい書類作成および書類管理のありかたです。これが、前提の大目的です。これさえ押さえてくれれば、ほぼこのページで言いたいことは尽くされています。このページの残りの説明は、単にイメージを具体化するためのケーススタディです。
メンテナンス用の書類の概要

会社でリバース・エンジニアリングの手間の発生が起きるのは、経営者にとっても時間と予算のロスでしょう。また、リバース・エンジニアリングをさせられる側である社員も、利益を生み出すわけではない作業に時間を多く取られ、とても負担です。なのでとにかく、リバース・エンジニアリングの発生予防が必要です。
メンテナンス用の書類の概要

で、具体的にどうすればいいかというと、リバース・エンジニアリングの発生を防ぐためには、なんらかの方法で、少なくとも主要な変数や関数と、その設計意図の対応表のようなものが必要です。
メンテナンス用の書類の概要

(完成図である)設計図だけでは、このような機能の解説をするのは不可能または困難なので、さらに変数・関数と、設計意図との、対応表のようなものが必要です。この対応表のようなもののことを本wikiでは「コード解説書」と呼んでいます(IT業界で何と言うのか知りません)。(設計図だけでも機能の解説を出来ているなら、その部分は解説書に書く必要はありません。)
メンテナンス用の書類の概要

要するに、機能と部品との対応表も残すべきだという亊です。「この部品、どの機能に対応してるの?」ってのが分かればいいのです。
メンテナンス用の書類の概要

異業種の例ですが、下記の2つの回路の図面を見比べてください。
メンテナンス用の書類の概要

どう比べても、右の「フロー図」のほうが、仕組みが分かりやすいでしょう。もし回路設計の専門外の素人が上記の回路図面を見ても、フロー図のほうなら機能が一目瞭然です。
メンテナンス用の書類の概要

このように、部品と機能を比べる書類があれば、とても後任者がラクになります。
メンテナンス用の書類の概要

また、このような部品と機能の対応の書類を作っておくことで、設計ミスの防止にもつながります。
メンテナンス用の書類の概要

上記の図面の例は、電気回路の設計の業界のハナシなので、ITではないですが、ともかく、こういう部品と機能の対応表があると、仕事がいいカンジです。
メンテナンス用の書類の概要

「フロー図」だの「コード解説書」などの名前はどうでもいいです。重要なのは、部品と機能の対応表を残しておけ、という事です。
メンテナンス用の書類の概要

逆に言うと、部品と機能の対応が分からないような書類ばかりを作っていても、無駄です。
メンテナンス用の書類の概要

けっして、やみくもに「○○設計書」のような名前の書類をいくつも残すのではないべきです。目的である、「部品と機能の対応表」を忘れないようにしましょう。
メンテナンス用の書類の概要

IT業界でこういう書類を残しているか知りませんが、少なくとも電子回路の業界では、こういう書類を残しています。けっして、(ブラック企業だらけだと悪評高い)日本IT企業の習慣のマネではなく、世界に冠たる競争力をもつ日本のB to Bの電子機器の製造業の手法をマネしましょう。
メンテナンス用の書類の概要

一般の企業でのITソフトは、発売後から10年後や20年後にもメンテナンス等が必要な場合があるので、コードの全体構造の解説書が必要なのです。たかが1~2年で流行の廃れるソフトの管理手法なんか、手本にしてはいけません。
メンテナンス用の書類の概要

コード解説書を書かない場合、それでも将来的なリバースエンジニアリング予防のために解説を残したい場合には、おそらくですが、代わりに「仕様書」などの既存の種類に流用で、変数名や関数などの指定を記載したりする必要が生じるかもしれません。ソフトウェアの設計図(完成予想図)はその性質上、解説などはあまり長く書けません。それはそれで一つの方法です。勤務先などに応じて、うまく方法を選んでください。
メンテナンス用の書類の概要

しかし、個人製作ソフトの場合、仕様書は無いのが普通なので、簡易的にコード解説書を書いたほうが早いかもしれません。プログラミングは、仕事や学業などの都合で中断される場合もありますが、再開後に、中断前のアイデアなどを思い出すためにも、コード解説書は書かれていると便利です。(コレがないと、時間が経つと、ほぼ作業内容を忘れる。)
メンテナンス用の書類の概要

さて、経団連企業などの東証一部の上場企業のIT業界の人が「仕様書を書かないと、あとでコードの仕組みを忘れる」とか言ってるのは、きっと、このコード解説書のことでしょう。経団連発言の時代的な文脈的に、けっして要件定義書とか完成予想図とかのことではないハズなので、勘違いしないようにしましょう。
メンテナンス用の書類の概要

このコード解説書の書き方には、けっして、決まった書き方がありません(なので、市販の入門書では、紹介されてない)。ですが、ともかく、経団連企業とかの技術系企業の設計部門では、こういう書類も書くのが望ましいとされています。
メンテナンス用の書類の概要

重要なことは、コードのどの部分が、ソフトウェアのどのような機能を実現するために、何を構成しているかと言った情報を、コード解説書または仕様書などで残すことです。
メンテナンス用の書類の概要

システム構造を解説するには、要するに変数名や関数名や、モジュールが、設計図に示した設計意図にどう対応しているかを、記載できれば良いのです。こういった大目的をまず忘れないようにしましょう。
メンテナンス用の書類の概要

では、どうやったら、こういう解説をできるのかを、これから考えていきましょう。
メンテナンス用の書類の概要

ソフトウェア開発前には実際のシステム構造(プログラムをどういう仕組みにしたとか、変数名をどうつけたか、とか)を書くのが難しいので、ある程度、開発が進んでから、開発中にシステム構造を書くことになります。
メンテナンス用の書類の概要

このコード解説書には、決まった描き方がありません。(なので、一般むけの「仕様書の書き方」入門書では、紹介されていない。)
メンテナンス用の書類の概要

なお、この「コード解説書」書類の呼び名は特に決まっていません。呼び名が無いと不便なので、とりあえず「コード解説書」と呼ぶことにします。
メンテナンス用の書類の概要

まず、ソフトウェアのシステム構造を解説する場合、どのファイルがエントリポイント(コンパイル時に最初に呼び出されるファイル。Main関数などがある)なのか、そういうことから、コード解説書に書いてください。
メンテナンス用の書類の概要

C言語にはファイル分割という機能があり、ソースファイルを複数のファイルに分割できますので、実際のソフトウェアではファイルが何種類もできます。
メンテナンス用の書類の概要

なので、コード解説書にエントリポイントがどのファイルなのかを書いてないと、いちいち読者がファイルを開いて読まないと、どのファイルが最初に呼び出されるのかを理解できません。
メンテナンス用の書類の概要

ファイル分割されたファイルが幾つも(いくつも)ある場合、例えばゲームソフトだとして、ジャンルがRPGなら
メンテナンス用の書類の概要

などのようにファイルが幾つもある場合、
メンテナンス用の書類の概要

システム構造書に、
メンテナンス用の書類の概要

などのように、それらのファイルが何を処理しているのかを第三者が分かるように書いてください。また、なるべく箇条書きで書くのが、読みやすくて便利でしょう。
メンテナンス用の書類の概要

当たり前に残すべきメモのように思えるかもしれませんが、しかしこういったメモが残されてない職場は多くあります。悪い見本です。とにかく、瑣末なことでリバース・エンジニアリングを後任者にさせないように書類を残す習慣をつけましょう。
メンテナンス用の書類の概要

ダメな一般IT企業だと本当によくあるパターンで、ファイル解説の書類など何も残ってないのに自社アプリのファイルサーバーには「system.cpp」などの漠然とした名前のファイルだけがいくつもある場合が時々よくあり、「systemって何のシステムだよ・・・」と後任者があきれたくなるファイル名のプログラムがいくつもある場合、これは大変にリバース・エンジニアリングの手間を発生させる、プログラマーにとってイヤなパターンです。
メンテナンス用の書類の概要

暗黙の前提ですが、画面名やファイル名などの名前を決める際には、具体的な名前をつけるべきです。
メンテナンス用の書類の概要

書籍『ゲームプランナー入門 アイデア・企画書・仕様書の技術から就職まで』によると、ゲーム業界でもそう指導されています。
メンテナンス用の書類の概要

ゲーム業界に限らず、一般のIT業界でも同様に具体的に命名するべきでしょう。つまり、「file1.cpp」とか「a.cpp」みたいなファイル名は厳禁です。また変数名でも「b」とか「variable1」(英語でvariableとは「変数」という意味)みたいな変数名は避けてもらいたいです。
メンテナンス用の書類の概要

なお、一般企業では箇条書きの説明をするとき、よくエクセルなどの表形式で説明することもあります。
メンテナンス用の書類の概要

のような表形式でよく箇条書きが書かれます。
メンテナンス用の書類の概要

開発した原作者には、「ファイル名から予想がつくだろ?」と当然に思うことであっても、意外と、通じない場合がありますので、きちんとコード解説書に、ファイルの処理内容を文章で書くべきです。
メンテナンス用の書類の概要

例えば、RPGの「メニュー」と言われても、あなたは「道具」「装備」などの画面を思い浮かべても、ほかの人は、戦闘シーンの「戦う」「逃げる」などのコマンド画面を思い浮かべるかもしれませんし、あるいは会話イベントの「はい」「いいえ」などの返事の選択画面を思い浮かべるかもしれません。
メンテナンス用の書類の概要

また、「マップ」 map と言われても、あなたは「主人公が現在いる場所の周囲」を思い浮かべても、ほかの人は、道具「地図」を使うと画面表示される世界マップと、世界地図のなかでの、主人公のいる地方の位置を思い浮かべるかもしれません。
メンテナンス用の書類の概要

または、「洞窟などのダンジョンの構造が書かれた地図のような道具が、そのゲームの中にあるのでは?」とか想像する人もいます。
メンテナンス用の書類の概要

このほか、数学用語で「map」(日本語でいう写像(しゃぞう)のこと)という用語がありますので、それと混同される場合もあります。
メンテナンス用の書類の概要

このように、ファイル名だけだと、いろいろと想像されてしまいます。
メンテナンス用の書類の概要

なのでコード解説書を作る場合、もし仕様書側に解説が無い項目なら、そのファイルのソースコードを読まなくても理解できるように、きちんとファイル内容の要約を解説書に書きましょう。
メンテナンス用の書類の概要

このほか、どうしても「System.cpp」とかのような漠然とした名前のファイルがある場合、何のシステムなのか、わかるように書いてください。(そもそも、そういう漠然とした名前を避けたほう安全ですが。)
メンテナンス用の書類の概要

たとえばRPGを作るなら、
メンテナンス用の書類の概要

などのように、そのゲームで使うパラメーターについて、ひととおり、変数名と、その内容の要約を書いてください。
メンテナンス用の書類の概要

たとえ原作者には「当然だろ」と思えることであっても、他人には意外と通じません。
メンテナンス用の書類の概要

たとえば、「defence_power」と言われても、仮にアナタは「防御力」のことだと思っても、ある人は
メンテナンス用の書類の概要

とか、思うかもしれません。
メンテナンス用の書類の概要

また、防具の防御力と、人物の防御力とを、同じ変数にするか、違う変数にするのかどうかも、「defence_power」という名前だけでは分かりません。
メンテナンス用の書類の概要

でも「人物の防御力」というように要約があれば、「あっ、防具の防御力は、人物の防御力とは別の変数なんだな!」って分かります。
メンテナンス用の書類の概要

また、
メンテナンス用の書類の概要

のような、魔法のような非現実的なファンタジーを前提にしたパラメーターがある場合、そのパラメータが何に影響をするのか、仕様書のほかの部分に書いてください。
メンテナンス用の書類の概要

例えば、
メンテナンス用の書類の概要

上記の要約だけでは、疑問がどんどんと出てきます。
メンテナンス用の書類の概要

市販のRPGでも、「魔力」「賢さ」「精神」の数値が増えると、何に影響するかは、ゲームごとに違います。
メンテナンス用の書類の概要

つまり、
メンテナンス用の書類の概要

などのように、何によって決定されるのかを、書いてください。
メンテナンス用の書類の概要

もし要件定義書など別の書類に書いてあるなら、それを参照する形で簡略化してもいいですが、しかし要件定義書には一般に変数名(「attack_power」とか)は書かれていないので、やはり、こういうコード解説書も作っておくのが良いでしょう。
メンテナンス用の書類の概要

たとえ、コード解説書の記述が、他の書類と説明がいちぶ重複していても、かまわないでしょう。
メンテナンス用の書類の概要

むしろ、他の書類と相互に照合することにより、設計ミスなどを見つけやすくなる場合もあります。
メンテナンス用の書類の概要

とはいえ、コードのすべてを解説するのも時間的に困難なので、説明に優先順位をつけ、設計者に必要なことを優先して書くようにしましょう。
メンテナンス用の書類の概要

なお、このコード解説書を書く場合、けっして単に「どこの変数の内容がいつ、どういう内容に変わる」とかだけを書くのではなく、その作業を通して何を実現しようとしているのか等の意図も、書くようにしましょう。
メンテナンス用の書類の概要

自分の書くコード解説書でバグのある内容を記述してしまうというミスをしてしまう場合もあります。なので、万が一、そういうミスをしてしまった場合に、将来的に仕様書を読まされる後輩たちが修正しやすくするためにも、できれば各コードの意図・目的なども併記するようにしましょう。
メンテナンス用の書類の概要

たとえ執筆時点でバグは無くとも、ソフトウェアによっては将来的にOSやらミドルウェアやらの変更が必要になったりする場合もあり、そういう場合に既存の仕様では動作しなくなる場合もあるので、仕様に変更の必要が生じる場合もあります。
メンテナンス用の書類の概要

もちろん、細かいことはソースコードにコメント文で書け済みますが、しかしもしソース側でかけないような事があれば、解説書の側で書くと良いでしょう。
メンテナンス用の書類の概要

なので、そういった将来のミドルウェア変更のような事態も見越して、特に重要になりそうな各プログラムがあれば、そのプログラムの作業内容の意図・目的なども、できれば、どこかに書いておきましょう。
メンテナンス用の書類の概要

とにかく、それぞれの書類で説明が他書類と重複していて説明文がやや増えても、説明の多いぶんには、デバッグが効率化するので問題ないのです。仕様書の分野では、説明の「大は小を兼ねる」です。
メンテナンス用の書類の概要

後任者が、仕様書や「要件定義書」や「○○設計書」などの各種の書類などを読むのは、仕組みを把握したり完成目標を確認する理由のほかにも、前任者の開発の経緯やそれにともなう思考の経緯を知りたいという理由もあります。
メンテナンス用の書類の概要

たとえば、もし古いソフトに不具合が出たときなどに、設計ミスなので設計変更が必要ですが、 後任者がどこの設計部分がどういう事情でそういう設計になったかが分からないと、後任者がどう設計変更でイジレナイからです。
メンテナンス用の書類の概要

(実際には書類不足などで前任者の意図が分からない場合も多く、そのため、テストを頻繁に繰り返すことになり、工期が増えて残業なども増えてしまったりします。)なので、もしも書類がうまく残っていて、前任者の「こういう理由で、こういう設計にしました」という設計者の思考の経緯が書類に残っていれば便利です。というか、それが無いと困ります。しかし困ったことに、無い場合が多いので、日本の技術者はよく困ります。
メンテナンス用の書類の概要

設計者の思考の経緯を伝えられるような、そういう定型の書類形式というのが、ありません。「要件定義書」、各種の「○○仕様書」、「△△設計書」などを見ても、そこには通常、思考の経緯は書かれていません。
メンテナンス用の書類の概要

「要件定義書」や「○○設計書」などは無いよりかはマシで、思考の経緯などを推測するヒントにはなりますが、あくまでヒントどまりです。 「部品と機能の対応表」のようなものがあれば、かなりヒントにはなりますが、しかし、それでもヒントどまりです。
メンテナンス用の書類の概要

なお「部品と機能の対応表」の目的は、けっしてヒント目的だけでなく、設計内容のチェック用資料や他ソフトなどとの連携をする際の資料なども兼ねています。なので、たとえ思考の経緯を残した書類を書けても、「部品と機能の対応表」の種類も書類作成を省略せずに作るべきです。
メンテナンス用の書類の概要

とにかく、後任者のために書類を残すとき、思考の経緯もうまく手短かに分かるように書類も作りましょう。
メンテナンス用の書類の概要

このコード解説書のページ数は特には決まっていませんが、おおむね、持ち運びやすい程度の厚さになるページ数にしておくべきでしょう。
メンテナンス用の書類の概要

この手のメンテナス資料でよくあるトラブルが、退職エンジニアの資料紛失です。
メンテナンス用の書類の概要

会社の上司が、メンテナンス資料の定期チェックをサボりたいあまりに、担当エンジニア個々人のパソコンにだけ資料を保存させておいて、そのエンジニアが退職などしたときに資料が紛失するトラブルが日本各地で多発しています。(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない場合が多い。)退職したエンジニアの使っていたパソコンは、次の新人のためにフォーマット初期化するので、フォーマットの際にメンテナンス資料も消えてしまうというトラブルです。
メンテナンス用の書類の概要

「会社の共有フォルダにメンテ資料を置きましょう」と提案しようにも、しかし上司のチェックすらされてない資料が共有フォルダに置かれるわけもないので、結局はそういう会社ではエンジニア個人のパソコンでメンテ資料を管理させられたりもします。そして、いつしかメンテ資料が消失しています。
メンテナンス用の書類の概要

この手の資料消失のトラブルを未然防止する簡単な方法は、定期的に、部署の部長課長などや上司などの管理者が、現場エンジニアから上がってきたメンテナンス資料の原稿を、(管理者が)定期的にチェックする必要があります。
メンテナンス用の書類の概要

また、こうやって定期チェックすれば、万が一、メンテ資料消失しても、資料を普段から検査してきた上司や検査担当者の頭の中に記憶が残っているので、ノウハウの復旧が比較的に容易です。
メンテナンス用の書類の概要

しかし、部長や課長などが原稿チェックを面倒くさがっていると、上述のようなトラブルになります。
メンテナンス用の書類の概要

どこの技術系の企業でも、設計図のチェックは念入りに行いますが、しかしメンテナンス用資料のチェックが省略されたりする会社が多くあります。 資料紛失は会社側の自業自得でもあります。
メンテナンス用の書類の概要

なお、上司がチェックを面倒くさがっているという理由でメンテ資料が個人管理されている場合、当然、その資料は印刷などはされていません(もし印刷すると、正式資料と混同されるので、紛らわしいから、印刷しない)
メンテナンス用の書類の概要

なので、退職しなくても、ハードディスク故障などが起きればメンテ資料は消失して一巻の終わりです。
メンテナンス用の書類の概要

退職が決まったときに会社は引継ぎ資料をエンジニアに作成させようとしますが、当然、上述のような技術資料が急に作れるわけもなく、そもそも資料の内容が上司や同格の技術力のエンジニアから検証チェックもされてないので信頼性も不明だし、よって急ごしらえの資料作成は大抵、失敗に終わります。
メンテナンス用の書類の概要

根本的な原因は、メンテ資料のための作成費用を普段から出していなかった会社の態度です。また、この手の会社は、そもそも論として、退職エンジニアより昔の前任者からのメンテ資料すら用意していないのが通例です。そんな杜撰(ずさん)な管理体制なので、大抵の企業では、急ごしらえのメンテ資料の作成は失敗します。会社の自業自得です。
メンテナンス用の書類の概要

つまり資料消失であわてる会社というのは、そもそも、まともにメンテ資料の上司によるチェックもしていなかったという会社であり、いろいろと自業自得です。
「単位動作」という概念

主に機械工学教育の用語なのですが、「単位動作」という用語があります。
「単位動作」という概念

たとえば、熟練工の動作は、一見すると色んなスキルを習得しているので複雑に見えますが、しかし動作のひとつひとつは、たとえば卓上ボール盤なら教科書どおりの卓上ボール盤の使い方ですし、やすりがけ の動作も、教科書どおりの動作です。
「単位動作」という概念

複雑な動作も、教科書どおりの動作を、組み合わせただけに過ぎません。
「単位動作」という概念

そして、その やすりがけ だけの動作の説明も、図や写真などを使って、「手順1:○○をする。」、「手順2:△△をする。」などと一段階ずつ、1ステップも抜かりなく 教えます。
「単位動作」という概念

だから、工業高校や大学の機械工作実習では、教科書どおりの動作をひとつずつ、教えます。
「単位動作」という概念

けっして、いっぺんにまとめて、別種の動作を教えません。
「単位動作」という概念

このように、動作をひとつひとつの単純な動作に分解することを単位動作といいます。
「単位動作」という概念

なぜ、わざわざこんな事を説明するかというと、世間では複雑な物事を説明するときなのに、いっぺんに教えたがる人がいます。しかし、そういう教え方は、多くの開発現場ではNG(エヌジー、ノー・グッド)です。
「単位動作」という概念

残念なことに、インターネット上には、一見すると説明書の文章量が多くても、実態を読むと、このような作者以外でないと操作方法を読み解けないようなダメな説明法をされているツールも、残念ながらネットに多く公開されてしまっています。
「単位動作」という概念

単位動作を意識した解説の書き方は、べつに難しくなく、普通に、 たとえばwindowsのオフィスソフトなどのヘルプファイルや、あるいはオフィスソフトについての市販の操作解説書のように、 「~~をしたい」といった操作目的の種類ごとに一個ずつ手順を段階的に教えればよいだけです。
「単位動作」という概念

単位動作の説明を軽んじる人が根本的に勘違いしていることは、「複雑な動作を練習したほうが、スキルが上達する」という勘違いです。
「単位動作」という概念

むしろ物理学の公式のように、単純で短いものに置き換えたほうが、物事を考える際の部品として使いやすくなるのです。 だから実際の順序は、「単純な動作を見つけ出すために、その何倍もの練習や試作をする」のです。たとえるなら、発明家の努力のようなものです。「99%の努力の上での、1%のひらめき」です。
実社会のデータベースでは過去データは消さない

在庫管理ソフトで、もし在庫部品データで、購入元メーカーで生産中止になったりした部品があっても、一切、在庫データベースからは登録を消しません。
実社会のデータベースでは過去データは消さない

もし消したりすると、次の登録番号の部品との登録情報の連続性が無くなり、登録データが飛び飛びになるので、大変に管理が難しくなるからです。
実社会のデータベースでは過去データは消さない

だからともかく、生産中止部品のデータベース管理では普通、その部品の末尾コメントに「生産中止」などと書き足すだけにして、登録そのものは維持します。
実社会のデータベースでは過去データは消さない

また、自分が使っていなくても、過去の自社製品を購入した客先がその部品を組み込まれた自社製品を使っている場合もありますので、残す必要があります。
実社会のデータベースでは過去データは消さない

だからもし、生産中止でなく単に入力ミスなどで登録済みの部品をまた登録してしまったことが判明した場合も、 最新の登録IDでない限りは、消すのではなく、末尾コメントに「登録ミス。すでにID○番で登録済み。」のような記録を書いて残したままにするのです。
実社会のデータベースでは過去データは消さない

こういうのはデータベースを運用する際の基本テクニックです。
実社会のデータベースでは過去データは消さない

製造業の図面などの「部品表」の番号でも、同じようなテクニックが使われます。設計変更により過去の廃止になった部品に当てられていた番号は、消すのではなく、新規の番号を確保して、その新規番号に代替の新部品を割り当てるというテクニックです。
実社会のデータベースでは過去データは消さない

また、「登録IDを最整列して並び替える」なんてことは、一切、しません。そもそも、在庫ソフトにそのような機能も原則、ありません。
実社会のデータベースでは過去データは消さない

なぜなら、すでに紙に印刷した実物の台帳に保管されている登録ID番号までを、在庫管理ソフトで書き換えることは不可能だからです。
実社会のデータベースでは過去データは消さない

一般に在庫の台帳は小さな事業所でも数千種類の在庫部品があるので、台帳にあるその数千種の再チェックをするのは時間の無駄なので、並び替えはしません。もし在庫番号の並び替えをすると、「本当に並び替え後の番号が合っているか?」などのチェックの手間が生じます。
品質の検証

製造業でもIT企業でも品質の検証は、部品ごとの検証と、全体の組立てをしたあとの検証という、最低でも2段階です。
品質の検証

少なくとも、自動車業界はそうです。
品質の検証

個々の材料部品などは、実際に引張り試験や荷重試験などを実際に物理実験を行い、部品の耐久値が規定や要求仕様を満たしているかを、事前に確認します。そして自動車の走行試験や衝突試験などは、実際に部品を組み立てて製品の状態である自動車にしてから走らせて見るしか、方法はありません。
品質の検証

チェックにおいて、シミュレーションなどは無駄です。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もありません。
品質の検証

「チェックの最終確認においてシミュレーションが無駄」といのは、これは自動車業界だけでなく、航空宇宙などでも同様です。日本のJAXAは「はやぶさ」の部品モジュールの開発において、実際に部品を組み立てたうえでの(シミュレーションではなく)物理実験をしています(※ 講談社ブルーバックス『小惑星探査機「はやぶさ」の超技術』で確認できます。)。
品質の検証

また、産業技術総合研究所での測定の国家標準器開発などでも同様の手法であり、実際に測定器を製品として組み立てた上での物理実験をしています(テレビ番組では、TBS科学番組『夢の扉』でメタンハイドレート採掘の産総研の研究者が、そうシミュレーションの問題点を指摘しました)。
品質の検証

ソフトウェアの開発では原理的に物理実験は無理ですが、それでも不具合対策の確認は、最終的には、実際にそのソフトをユーザー視点で使用してみる「実践」/「試用」しかありません。
品質の検証

ソフトウェア業界だと、個々の部品ごとにチェックすることを「単体テスト」といいます。一方、全体的に組みたててみてチェックすることを「ビッグバンテスト」と言います。
品質の検証

さて、チェックにおいて、シミュレーションなどは無駄であり。なぜなら、もしそのシミューレション手法自体にバグや不具合が潜んでいたら、元も子もないのでした。
品質の検証

ではシミュレーションの意義は何かと言うと、工業系に強いライター(「文筆家」の意味)の山根一眞『メタルカラー』シリーズのどれかに書かれていると思いますが、意義はけっして直接のチェックではなく、既に行った物理的な検証実験をもとにそれをシミュレーションと照らし合わせることにより相互検証することで、検証回数を減らすことにより費用節約するのが目的です。
品質の検証

たとえばシミュレーションなしでは20台の機械装置を耐久実験のため壊さないといけない工程であると仮定して、もしシミュレーションありなら耐久試験で壊すのは12台ですむ工程にできるなら、今後の自社の新製品では8台ぶんの費用が節約できます。そういうコストダウン投資のためにシミュレーションをするのです。
品質テスト

ソフトウェアのテストは、IT企業では、よく新人がやらされる仕事でもあります。新人研修に組み込まれていたり、研修明けによく与えられる仕事でもあります。
品質テスト

なぜなら、自社ソフトウェアの内部構造の知識が乏しくてもテスト自体は可能だからです。
品質テスト

製造業などでも、多品種少量生産の設備機械そのものの生産では、たとえば簡易的な耐久試験などのために「実機のボタンAを押した後に画面遷移後にボタンBを押すのを、50回繰り返す」みたいな簡易的かつ長めの時間の繰り返しテストは、よく新人の仕事です。(なお、50000回の繰り返しみたいにテストが長すぎると人間じゃ無理だし(機械で繰り返すことになる)製品が磨耗して壊れたり製品寿命が大幅に減るので、せいぜい人間でも可能な500回くらいまでにとどめて、人間がテストしたりします。)
品質テスト

どの業界でも、テストのうち、時間の掛かる繰り返し試験は、よく新人に与えられる仕事です。
品質テスト

いちおう、設備機械の組立て直後の段階で、「ボタンAを1回だけ押すテスト。ボタンBを1回だけ押すテスト。」みたいな(繰り返しでない)短時間テストは、機械を組み立てした生産者本人が現場で行います。しかし、「500回繰り返す」みたいな仕事は長いので、新人がテスターを行うのがよくある会社風景です。
オーバーエンジニアリングを避ける

「オーバーエンジニアリング」(over engineering)という用語があり、善かれと思ってもか、余計な設計をしてしまう事です。」
オーバーエンジニアリングを避ける

たとえばソフトウェアの設計の場合、あらゆるバグを想定して個別に対応したコードを書こうようとしてしまうと、コードが長大になってしまい、保守性がいちじるしく低下してしまいます。
オーバーエンジニアリングを避ける

システムのあらゆる部分にバックアップを持つのも、時間的にも費用的にも不可能であり、オーバーエンジニアリングです。
オーバーエンジニアリングを避ける

製品と寸分も違わぬデザインパターンを追求しようとして、ろくに実装もしないのもあります。また、そのような発想で書かれたマニュアルは、膨大な学習コストが必要であり、実用性が乏しいです。
オーバーエンジニアリングを避ける

最小限の機能だけのプロトタイプを作る手法です。
オーバーエンジニアリングを避ける

生命などの安全にかかわるものでもないかぎり、失敗を許容しましょう。
オーバーエンジニアリングを避ける

機能が実際に必要になるまで追加しない方法です。
オーバーエンジニアリングを避ける

ソフトウェアの場合、あとからでも比較的に容易に追加できることが多いので、こっちのほうが良いでしょう。
オーバーエンジニアリングを避ける

ただし、航空宇宙や造船などは別かもしれません。