良いドキュメント・マニュアル・仕様書を書くスレ
■ このスレッドは過去ログ倉庫に格納されています
0001デフォルトの名無しさん
NGNGドキュメントを書ける自信はあるか？
仕事で納品したり、他人に見せるプログラムとして公開するつもりなら、
マニュアルや、仕様書などのドキュメントを書く機会は必ずある。
プログラムとドキュメントはとても関係が深い。ドキュメントが整っていない
プログラムなど、ゴミと同じ。それに、ただ書けばいいって物でもない。
ドキュメントがゴミ程の役にも立たなければ、結局それはゴミなのだ。
だらだらと書いた意味不明な文章を他人に見られるのも恥ずかしいよな？
いわばドキュメントを書く技術はプログラマの必須スキルの１つなのだが、
実際は、下手糞なドキュメントが蔓延っている。(これはGNU製に多い)
読んでも無駄とか、書いても無駄とか思ってる奴、その考えを改めろ。
プログラムに対するドキュメントを、ちゃんとした１作品として、
後世に残せるよう努力すべきだろう。
今一度問う。
おまえら、わかりやすく的確なドキュメントを書ける自信はあるか？
0599デフォルトの名無しさん
2008/05/28(水) 23:41:27ソース内のコメントをちゃんと書け！
と思う、インフラ屋は俺だけではないはず。
特にリリース後の修正箇所に対して正確な
コメントが書かれているソースが本当に少ない。
頼むから引数のコメントくらい、まともに書いてくれ・・・・
0600デフォルトの名無しさん
2008/05/30(金) 04:18:140601デフォルトの名無しさん
2008/05/30(金) 13:08:410602デフォルトの名無しさん
2008/05/31(土) 00:23:06> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。
これはコミットログやChangeLogの役目だろう
0603デフォルトの名無しさん
2008/05/31(土) 13:13:14ソース内のロジックとコメントは分業してるってこと？
ロジックとそのコメント内容が一致してないから
障害対応してるときに頭からソースを読まなければ
ならないってこと。
そして、修正したPGはすでにいないことが多い・・・・
0604デフォルトの名無しさん
2008/05/31(土) 17:32:04コメントとソースを同じように扱ってはいけないだろ
0605デフォルトの名無しさん
2008/05/31(土) 18:51:02ただ最初にも書いたけど、表題部の
プログラム名や用途、引数説明すら
まともに書いてないソースが多すぎる
からカキコしただけだ
0606デフォルトの名無しさん
2008/05/31(土) 19:19:501.5.5平気なんだけど
0607デフォルトの名無しさん
2008/05/31(土) 21:19:450608デフォルトの名無しさん
2008/05/31(土) 22:24:13> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。
これは 「こう修正しました」 っていうコメントのことでしょ？
それはまさにコミットログ等の役割
コードからは読み取れない 「こういう処理です」 っていうのがコメントの役割だと思う
0609デフォルトの名無しさん
2008/06/01(日) 01:34:08"「こう修正しました」"は
ソース内の修正(変更)履歴のことを言ってる。
0610デフォルトの名無しさん
2008/06/01(日) 01:53:13そりゃあSCMがない時代の苦肉の策でしょ
0611デフォルトの名無しさん
2008/06/01(日) 09:06:34バージョン管理使おうぜ
0612デフォルトの名無しさん
2008/06/01(日) 11:47:08今、休出でVSS見てるけど、コミットログやChangeLogは存在しない。
各ソースのチェックインコメントは全部一緒で"○○○○更改に対する修正"・・・・
ほかに見るとこあれば教えてくれ。
（インフラ側で作ってる基盤モジュールのアップデート履歴のほうが
詳細に記載している。）
0613デフォルトの名無しさん
2008/06/01(日) 17:35:45履歴を残そうという意識が作業者に無ければコミットログにも残るわけ無いだろ。
お前んとこのローカルな事情だな、それは。
で、一般的に履歴を残すんならどっちかというとコミットログのほうが適切という話。
0614デフォルトの名無しさん
2008/06/01(日) 17:43:21コミットログはチェックインコメントと同じ意味
ツールが違うと用語が違う
チェックインコメントが全部一緒だと無意味だと感じませんか？
チェックインコメントは修正内容を記録するのにうってつけだと思いませんか？
0615デフォルトの名無しさん
2008/06/01(日) 17:49:07コミットログならすぐ探し出せる。コメント漏れがあっても差分を見つけられる。
コミットログに情報がないというのは、結局コメントの入れ方、運用の問題でしょ。
0616デフォルトの名無しさん
2008/06/01(日) 19:27:14みたいな感じに見えた
0617デフォルトの名無しさん
2008/06/02(月) 15:25:20http://pc11.2ch.net/test/read.cgi/tech/1212144627/
0618デフォルトの名無しさん
2008/07/27(日) 04:43:220619デフォルトの名無しさん
2008/08/23(土) 14:10:15じゃだめかな。
0620デフォルトの名無しさん
2008/08/23(土) 18:05:570621デフォルトの名無しさん
2008/11/17(月) 15:02:59どれがいいだろうか・・・
C++Builder2007なんだけど。どれ対応してるかもまだ調べてないんだ。
とりあえず・・・探すか。
0622デフォルトの名無しさん
2009/02/07(土) 11:48:29何か適当な代替え手段はないでしょうか？
# 何年ソフト屋やってんだ？ BNFくらい読めよ > 某メーカの糞 SE
0623デフォルトの名無しさん
2009/02/07(土) 12:29:550624デフォルトの名無しさん
2009/02/07(土) 12:32:070625デフォルトの名無しさん
2009/02/07(土) 13:16:45要所で適切な名前をつけて分割してあれば読みやすいし、
BNF知らなくても直感的にわかると思う。
逆に、１行でだらだら書かれたりすると、いくら正しくても読みづらい
0626デフォルトの名無しさん
2009/02/07(土) 14:43:47先生「意味が分からない．」
0627デフォルトの名無しさん
2009/02/07(土) 17:25:110628622
2009/02/07(土) 17:42:31条件指定できる設定ファイル用なので、そんなに巨大なツリーじゃない
そもそも, BNF の読み方を知らないらしい
>>627
Pascal の構文定義に使ってある奴？ あれって、けっこう一般的なの？
つか、BNF と変わらないような気もするが…
大量の使用例を書くしかないのか？
0629デフォルトの名無しさん
2009/02/07(土) 18:58:290630デフォルトの名無しさん
2009/02/07(土) 20:30:03xxx *= yyy | xxx yyy
を
項 xxx は、単独の yyy または xxx に続く yyy によって定義されます。
とかの半分機械的な置換で済むかもよ。
0631デフォルトの名無しさん
2009/02/07(土) 22:55:31BNF云々というより、人との付き合い方の問題な気がする
TPOとか判ってないでしょ
他人のオナニー文書を読まされる側の立場にもなってみろ
0632デフォルトの名無しさん
2009/02/08(日) 01:39:27書き手：「お前のオナニー用エロ文書を書かされる立場になってみろ」
読み手：「他人のオナニー文書を読まされる側の立場にもなってみろ」
不毛な・・・
0633デフォルトの名無しさん
2009/02/08(日) 01:52:160634デフォルトの名無しさん
2009/03/07(土) 12:45:090635デフォルトの名無しさん
2009/03/07(土) 21:27:240636デフォルトの名無しさん
2009/03/07(土) 21:52:54どんなに文字を尽くして書いても、相手の頭にすっと入ってイメージを
作れないと負け。
駄目なドキュメントって、たぶんすべて書いてあるんだろうけど
量ばかり多くてツマラン推理小説みたい。筋の5W1Hがさっぱり見えないで
筋書きを楽しむ以前に何がなんだかわからないオナニーみたいなやつ。
0637デフォルトの名無しさん
2009/03/14(土) 03:43:34見せ合いっこはｺｰﾌﾝする
0638デフォルトの名無しさん
2009/04/10(金) 18:21:150639デフォルトの名無しさん
2009/04/12(日) 14:23:360640デフォルトの名無しさん
2009/06/13(土) 08:57:14学習目的で小さなプロジェクトを立ち上げようと思っているのですが、
各種ドキュメント（基本設計、詳細設計、テスト仕様書等）の雛形、規格のようなものは
どこかで公開されていないのでしょうか？
IEEEって団体が作ったものがあるようですが
無料ですぐに手に入るものではないようです。
他にどこか有名な団体が作成したものがあるでしょうか。
できれば日本語が好ましいです。
よろしくお願いします m(__)m
0641デフォルトの名無しさん
2009/06/15(月) 11:53:08行く場所場所でドキュメントの定義やスコープ、はたまた名称まで違ってて毎回混乱・・。
その場所のしきたりに慣れるまでストレスを追わにゃぁならん。
プロジェクトの規模にもよるから当然ちゃ当然だが、ドキュメント類は
大まかな指針のようなものに従って書いてもらいたいし、書きたいわけだ。
どこかの学者様かスーパーＳＥ様あたりが統一規格のようなものを打ち出してくれて、
それが広まってくれれば助かるんだがな。
0642デフォルトの名無しさん
2009/06/15(月) 12:47:00そもそも用語でさえベンダ間で互換性がないんだから、どうしようもないな。
0643デフォルトの名無しさん
2009/06/15(月) 16:25:34であるならば、新規プロジェクトを起こす場合、最大公約数的な雛形となるべき指針が
存在してもいいはずだと思わんでもない。
ま、下請けが納品する場合はどうあがいても、大手のフォーマットを利用せざるを得んのだろうが・・。
ちょっと探してみたんだが
ttp://www.hotdocument.net/
↑あたりはなにかしらのフォーマットを利用したんだろうか？
0644デフォルトの名無しさん
2009/06/15(月) 19:02:04普通そこらに転がってるドキュメントって、
＊＊＊ このように、できてます！！！ ＊＊＊ が、書いてあるだけで
＊＊＊このように作らなければならない理由＊＊＊ が、書いてない。
＊＊＊もっと上の仕様書との連続性もない＊＊＊ 場合がほとんど。
なので、メンテナンスの役に立たない。
0645デフォルトの名無しさん
2009/06/15(月) 21:11:58大手ベンダが専門の標準化チーム作ってフォーマットをガリガリつくってんのが現状。
派遣ソルジャーがデータ持ち出さない限り表にゃあ出てこねえよ。
0646デフォルトの名無しさん
2009/06/16(火) 06:58:09発注者視点ですが、開発者でも使えると思う。
0647デフォルトの名無しさん
2009/06/16(火) 14:37:32ttp://www.sage-p.com/process/process.htm
俺めんどくさいから目通してないがｗ
0648デフォルトの名無しさん
2009/06/16(火) 17:10:390649デフォルトの名無しさん
2009/06/16(火) 23:38:52■ このスレッドは過去ログ倉庫に格納されています