エンジニアとして働く方にご意見頂きたいです

WEBサイトの制作を外注しまして、以降自社で、エンジニアさんを呼んで、改修など手を加えたい場合、どのような書類があれば、エンジニアさんが内容把握しやすいでしょうか？

もちろん、WEBサイトの大きさや、エンジニアさんの経験などにもよると思いますが、
簡単に説明しますと

●PHPで開発している。
●オブジェクト指向である
●排他処理されているプログラムである
●SSL使用、決済機能付きである
●DBのテーブル内容（カラム）など、複雑に作成されている

設計書とか仕様書というようなものがあればと思うのですが、
制作会社によっても仕様書などの書き方って違うと思うんですよね？
ものすごくわかりやすいものなら良いのですが、そういう訳でもないかもしれない…

ちなみに、私は経験はPHPとmysql、オブジェクト指向の勉強程度で、画面遷移や仕様書などを見て改修した経験がないので、本当に想像で申し訳ないのですが

結構大きなシステムの紐解きを、エンジニアさんが、無理なく全体象を把握できるようなものがあればいいと思うのです。

そこで、仕様書でも良いけれども、以下のような書類で解決できないものか？
と挙げてみたのですが…


●各ファイル説明書
WEBサイトが動作するために使用しているファイルの名前と簡単な説明
（××に関するオブジェクトを記載したファイル、××の設定ファイルなど）

●オブジェクト説明書
WEBサイトが動作するために使用しているオブジェクトの名前と説明

●DBの設計書
WEBサイトが動作するために使用している各テーブル、各カラムの名前と詳細説明

●各ページからの画面遷移書
リンク詳細、ボタンクリックにより動作するものに関しては番号付加
（キャプチャーするなどで、自社でもできる）

●機能説明書
画面遷移書に記載された番号付きボタンに関しての機能説明

●サーバー設定などの説明書


以上のようなものがある場合、これはあまり必要ないとか、これは必要とか
また、もし、エンジニアとしては、こういうのがあると改修しやすい、仕様書に説明がある方が使いやすいなど、ありましたら、ご意見を頂きたいのです。

エンジニアさんとして活躍している方でも、こういったWEBサイトを経験した事がある方まで、
大変お手数お掛けしますが、エンジニアさんの立場のご意見を、お願いします。
できましたら、ご経験年数、どんな開発をされているかなど簡単にお書き添え頂けますと幸いです。

どうぞよろしくお願い致します。

No.1 ベストアンサー 回答者： Gaffgarion 回答日時： 2013/02/11 18:49

具体的ではなく抽象的な言い方ですが、

「やりたいこと(やりたかったこと)」「やれること」「やったこと」がまとまっていると良いですね。
ドキュメントがなかったり、散逸していたり、はよくあることです。
そうなるとソースを読んでいくことになるのですが、
「やりたいこと」「やれること」がまとまっていると「やったこと」であるソースが読みやすくなります。
仕様書、設計書などの名の付いたドキュメントがあっても、
「やりたいこと」「やれること」「やったこと」が理解できなければ意味がありません。

あと、内容が分からないので何とも言えませんが、業務と絡めたドキュメントも必要でしょう。
プレイヤーがいて処理があって金・物・情報がどのように動いて、、、
といったフローの中でシステムがどの部分を占めるのか、はあった方が良いでしょう。

ドキュメント作成の参考にしてみてください。