古今東西ドキュメントの書き方

おまいら、大いに語って下さい。
議事録から仕様書まで。こんなとんでもないドキュメントがあったとか、
こうすればもっとわかりやすいドキュメントが書けるとか。

ただ今仕様書につじつま合わせるための報告書づくりに四苦八苦してる漏れ。

今AAを探してるからちょっと待ってろ！

　 　 　　/~ヽ　　 /~~ヽ 　　ああ・・・
　 　 　　| 　|i ＿∧ゝ ﾉ 　あんまり面白いAA
　 　 　 ノ　ﾉ；´Д｀） / 　　なかった・・・　　
　 　　（　ノ　　　　 ソ
　 　 　 ヽ　　　　　 ヽ
　　　　　 ＼ 　　　　 ＼
　　 　　　　 ＼ 　　　　 ＼
　　　 ＿　　 ／　　 　 　　.＼ ＿
　　/ミ （⌒Ｙ.　　 ／￣.＼　 .＼　ﾐヽ
　 　 ￣ ＼ ,_ _,／　　　 　＼,_ _,ﾉ￣

仕様書は保守されないのが常なので、最良の仕様書はｿｰｽｺｰﾄﾞそのものって会社がいっぱいあるんだろうね...

議事録って書き方がひとつじゃないから好きじゃない。
これがベスト！というものがないものか…
議事録しっかりしてないと絶対にあとでトラブるしなぁ。

どう仕様もない
仕様がない
双仕様類
大海仕様
仕様撃波
別れま仕様
レ　ザア　マ仕様

仕様の流れ
お仕様さま
サッカー仕様ぜ
仕様っと待った
あっ仕様
仕様不能
仕様目薬
座仕様
仕様南
撒き仕様
仕様なき戦い
仕様の女神
う仕様ととら

>5
誰がどんな決定をしたっていう記録を残しておかないと、苦労するハメになるのは下の連中だからね。
もっとも、記録が残っていても苦労するハメになることも多いんだけど...

で？

仕様灯する時間です
イッツ仕様タイム
仕様量の酒
仕様来楽しみ

>6-7
イキロ

ソースコードが最良の仕様書ってことは、
本来の仕様書はバグだらけってことだ。
仕様書書いた奴の評価を下げるべきだな。

>12
本来の仕様書がﾊﾞｸﾞだらけって訳じゃない。
ﾌﾟﾛｸﾞﾗﾑが改修された場合にそれが仕様書に反映されることが少ないんだよ。

やっぱり文芸的プログラミングですか。（←よくわかっていない）

>>13
なぜプログラムが改修されるのか？

>15
ﾕｰｻﾞによる仕様変更とか機能追加が主要な原因。
短期の開発になるのでﾄﾞｷｭﾒﾝﾃｰｼｮﾝの時間がなかなか取れない。

ちょっと文章が正確じゃなかった。

×なぜプログラムが改修されるのか？
○なぜプログラムが仕様書に影響をあたえるレベルで改修されるのか？

>13
複数あるドキュメントの内、一部にだけ反映されているという罠。

｡･ﾟ･(ﾉД`)ﾉ･ﾟ･｡ ｳｧｧｧﾝ

WordとかExcelでdiffがとれればどんなに楽なことか…
「版の更新」ってMSだから危なっかしくて使いたくないし。

>>18
ありがちだね。

外部設計書と内部設計書を皆様のところで何と言うか
教えてください。
(Water fallで申し訳ない)

>>21
基本設計書と詳細設計書

21です。
私が昔いたところは機能仕様書と設計仕様書でした。

21です。
昔、ソフトウエア開発の講習会を受けにいったとき
要求仕様（Requirement Specification）と
設計仕様（Design Specification）という用語も
聞いたことがあるように思います(うろ覚え)。

21です。
>>17
ということで、なんらかの理由によるプログラムの変更は内部設計書には
簡単に影響を与えるし、場合によっては外部設計書にも影響を与えるのでは
ないでしょうか？

ん？　「なんらかの理由」って、結局、仕様に不備があったってことか？
ゴメン。

>>22
目立経験あり？

>>26
ここらあたりの喋りを聞くと訛り（accent）がわかりますよね。
「貴方XX訛りがありますね」とか、
「この文章はYY accentで記述されています」とか言えるかも。
標準語で喋れるようになりたい。

おいおまいら、日経ＩＴプロフェッショナルの特集いいぞ。
ドキュメントというよりプレゼンテーションの書き方だが。

仕様書作るの時間のムダ。ソースコード命。コメント書きまくり。
だってメンテされないわ、もともとＰＧというよりコーダ向けの書式だわ…。
もっとＰＧの裁量が大きくなるような仕様書研究しなきゃ。
ＳＥの仕事はまるで英作文の問題をつくるみたい。
それならＳＥがプログラムごりごり組んだほうが早い。
うちはそんな状況ですよ。

禿同意。

１．実際に作ってみないと細かいところまでわからない。
２．実際に作ってみないと何が可能で何が不可能かわからないことがある。
３．PG段階に入ったら仕様変更があったとき仕様書よりもPGを直すので
　　仕様書は後回しになる。
４．仕様書にこう書いてあると言ったって、客はどうしてもこうしてくれ
　　とだだをこね、「こうしないと統一感がない」とか「ユーザに不親切
　　だ」とか言って、結局仕様に沿って作っても修正が入る。

画面・フィールド定義
ＤＢ・ファイル・帳票・電文のレイアウト
処理概要
処理フロー
業務説明書
エラーメッセージ解説
システム構築や改善に至った背景と履歴

など

後から引き継ぐ者の身になってドキュメントを残しておいて欲しいなぁ

>>31
引き継ぐことになった当初はいつもそうしようと誓うんだけど、
いざ作り始めると時間がないとかなんとかで、結局中途半端。
ごめん。
最近数年前に自分が作ったシステムの改造案件が入って、あまりの資料の少なさに
自己嫌悪におちいってたりします。
当時は入ったばっかで何もわかってなかったというのはあるんですけどもね

仕様書は頭の中にある…。
暗黙知は形式知にしておかないといかんな。
自分が中心となって作った仕組みでも、
なかなか思い出せないところもあるからね。

伸びんな。このスレ。

操作マニュアル、運用マニュアル、導入マニュアル、
これら、結局excelで作ることにしてみました。
ちなみに最後に PDF 出力します。

PDFは軽くていいね。
障害対応のマニュアルは充実させておいてね。

Word2000で作ったドキュメント。Word2002で1文字修正して
保存したら、ファイルサイズが倍以上になりやがった！
どういうこっちゃ？

>>37
その1文字がビットマップだったという罠

保守age

>>37
Word98で同じようなことがあった。
98と同じ原因なら、今後も増え続けるよ、きっと。

新規文書を作成して、そこに全コピペすると
コピペした先では増えなくなった。

>>37
その文書をあと2回も上書きすると
印刷時にWordが落ちる可能性有り。
早めに>>40の言うように全コピぺで文書作り直しを勧める。

……以上、書式が死ヌほど面倒なWord文書で
ドキュメント書かされてたPGより。

ageてよかた