[過去ﾛｸﾞ] 良いドキュメント・マニュアル・仕様書を書くスレ (649ﾚｽ)
上下前次1-新
このｽﾚｯﾄﾞは過去ﾛｸﾞ倉庫に格納されています｡
次ｽﾚ検索 歴削→次ｽﾚ 栞削→次ｽﾚ 過去ﾛｸﾞﾒﾆｭｰ
1(2): 03/10/05 23:34 AAS
おまえら、自分で作ったプログラムについての、わかりやすく的確な
ドキュメントを書ける自信はあるか？
仕事で納品したり、他人に見せるプログラムとして公開するつもりなら、
マニュアルや、仕様書などのドキュメントを書く機会は必ずある。
プログラムとドキュメントはとても関係が深い。ドキュメントが整っていない
プログラムなど、ゴミと同じ。それに、ただ書けばいいって物でもない。
ドキュメントがゴミ程の役にも立たなければ、結局それはゴミなのだ。
だらだらと書いた意味不明な文章を他人に見られるのも恥ずかしいよな？
いわばドキュメントを書く技術はプログラマの必須スキルの１つなのだが、
実際は、下手糞なドキュメントが蔓延っている。(これはGNU製に多い)
省5
550: 2008/04/28(月)19:50 AAS
>>548
箇条書きにした？
551(1): 2008/04/28(月)19:51 AAS
>>549
もっと詳しく書けっていったから詳しく書いたんだが、ついでに数式まで交えて…
「例をだせや！！！」っても、「はじめてなんでありません」と…
552: 2008/04/28(月)19:52 AAS
>>545
そういえば、VSってソース解析する上にマクロからアクセスできるんだったな。
ドキュメント自動生成マクロなんかあってもよさそうなのにな。
何とか工房がそうなのか？
553: 2008/04/28(月)20:10 AAS
>>551
相手が理解できない点を、推測じゃなくて、ちゃんとヒアリングするのは無理なのか?
あと、説明するときは、いきなり本物じゃなくて、ミニマムセットで理解できるかどうか確認するとか。
そこらへんにギャップがあると、「それじゃわからん」vs「ではどう書けと」の対決になるような希ガス。
554: 2008/04/28(月)21:32 AAS
プロトコルなんだから、シーケンス図？（自分対相手でメッセージを線で表現した奴）も
必要なんじゃない？
555: 2008/04/28(月)22:06 AAS
自分<-- メッセージ -->相手
こうかｗ
556(1): 2008/04/28(月)23:24 AAS
通信プロトコルならシーケンス図がいいんじゃないか？
状態遷移図と突き合わせできるように書けばOK
557: 2008/04/28(月)23:33 AAS
>>556
しかし、シーケンス図だと条件分岐がすごく書きにくくない?
558: 2008/04/29(火)01:20 AAS
パターン別に何種類か書いたらよかろうが
559: 2008/04/29(火)01:28 AAS
組み合わせ爆発しなきゃそれでいいかもしれんが……。
560: 2008/04/29(火)12:28 AAS
プロトコルってのは「やりとりの規約」だかんな
やりとりに出てくるもの全てを図に入れて，なおかつどんなやり取りが行われるのかを書かないといけないんでないかい？
でもヒアリング一発ですみそう
561(1): 2008/04/29(火)12:46 AAS
rfcでも参考にして書けばいいんでない？
562(1): 2008/04/29(火)14:38 AAS
>>561
RFC を参考にしてではなく RFC 提出できるくらいまじめに書いた
だけど、定義してるのはプロトコルなんで
「実装する奴が理解でない！！！」
結局, フローチャート書きまくりだとか数式無しだとかじゃないと
駄目らしい
だけどさ、状態遷移図をコーディングレベルに落すのは
「あんたらの仕事じゃねぇの？？？」 >>25才位のクライアントの担当者
# つか、ステートマシンとか習わかったのか？
563(1): 2008/04/29(火)14:57 AAS
>>562
もしかして日本語がやばいんじゃないか？
564(1): 2008/04/29(火)15:12 AAS
>>563
おぉ、そうかもしれん ＞俺の日本語 Www
だれどさ、院出てから、10年以上この業界に巣食ってるけど、
いままでお目にかかったことがない ＞こんなクライアント
565(1): 2008/04/29(火)15:23 AAS
クライアントは何屋さん？
566(1): 2008/04/29(火)15:44 AAS
>>565
今まで、地方自治体外郭団体向けに事務処理ソフト作って{る|た}会社
>>564 書く直前に
「理工系の知り合いに聞いたら、うちが悪かった」
って，電話入ってきた。
まぁ、>>564 ただの愚痴だし、確に、俺も悪かった思うが………
こんなに、言語の差があるもんなのか？
567: 2008/04/29(火)16:41 AAS
とりあえず日本語でおｋ
568: 2008/04/29(火)16:46 AAS
まぁ、独自プロトコルを定義した仕様書を今まで見たことないんだろうね。
いつまでも自分流儀でやって、愚痴たれながしとけばいいよ。
569: 2008/04/30(水)00:07 AAS
事務処理オンリーだった会社じゃ通じなくても不思議はない。
不思議はないが不甲斐ないな、そこ。
570: 2008/04/30(水)02:15 AAS
>>543
VS2005ならDoxyCommentがいいんじゃね
書式もカスタマイズできるし
571(2): 2008/04/30(水)02:52 AAS
正直、ドキュメントが読めない
ＤＢの構成とか設計書とか。
「読んだら分かる」っていつも言われるんだけど、
どうしたらいいかな。
572(1): 2008/04/30(水)03:18 AAS
>>571
落ち着いてジックリ読んでみな。
573: 2008/04/30(水)10:43 AAS
>>566
そう言う所は、得てして「うちはどこそこの仕事をしているんだ」って妙な自負があるから
こっちが何を書いてもクレームつけるよ。謝罪の電話があっただけでもましな方かも。
# うっかりしていると、同じドキュメントを「概要」と「詳細」と「解説」の3バージョン作る羽目になったり。
574: 2008/04/30(水)13:11 AAS
これはいい勉強になるスレ
575(1): 2008/05/01(木)21:02 AAS
>>571
ドキュメントは読めるようになったほうがいいよ。人に
頼ることなく進む力がぐんと増える。(ドキュメントに
頼る時点で、というのは無しで)
どうしたらいいかと言われると解答に困るんだけど、
日頃から疑問に思ったことがあれば、まずドキュメントに
目を通すという習慣をつけてみたらどうだろう。
java でプログラミングしてて分からないことがあったら
まず javadoc を当たってみて、それでも分からなければ
ぐぐってみたりとか。
省2
576: 2008/05/02(金)10:31 AAS
それ、「〜ほうがいいよ」ってレベルじゃなくて、「〜できなきゃダメ」のレベルだと思う。
577: 2008/05/03(土)13:36 AAS
AA省
578: 2008/05/06(火)04:58 AAS
>>572
>>575
遅くなったけど、ありがとう。
疑問を持ったら人に聞くクセをなくすように
がんばります。
579(1): 2008/05/08(木)17:47 AAS
今度開発の仕事やらせてもらう事になりました。
その前に勉強として、仕様書作ってプログラム作れって上司から
言われました。
プログラムは作ったことあるんですが、仕様書なんて作ったことありません。
常識的に考えたら、基本設計書、概要設計書、コード設計書とか全部作るべきでしょうか？
580(1): 2008/05/08(木)20:27 AAS
上 司 に 聞 け
581(4): 2008/05/08(木)23:52 AAS
>>580
言葉足らずですみません。
仕様書って何の事か聞いたんですが、自由に作っていいって言われたんです。
自由に作れと言われたら基本的な概要、機能とか画面構成など書けば仕様書としては
成り立つんだと思うんですが、いかんせん初めての経験なのでどのように書いたらいいか
わからないんですよね。
社会人の常識として設計書の本読んで基本設計書、概要設計書
など全ての設計書を作るのが妥当なのかという質問です。
582: 2008/05/09(金)00:08 AAS
単なる練習プログラムなんだから概要からでいいんじゃね
583: 2008/05/09(金)03:44 AAS
上司乙ｗ
584: 2008/05/09(金)08:08 AAS
>>581
疲れたので途中で止めとくけど、こんな感じで読める読み物を作ればおけ。
ゴールの定義
・どういう背景があり（どういう歴史があり何で困っていたのか）
・何を実現したいと考えています（作ったものを使うことで得られると期待される効果のこと）
・このために何々をするものを作ることにしました
全体構造
・大きな制約条件として〜がある中で（納期、コスト、現状からくる技術?%A
585: 2008/05/09(金)08:09 AAS
あれ？途中で切れてしまった・・・
書き直すもの疲れたので諦めるすまん>>581
586(1): 2008/05/09(金)09:40 AAS
骨組みでこの程度がわかれば良い。
・なんで作ったのか
・それを使ってどういう効果が期待できるか
・必要とする環境
・入力は何か
・出力は何か
競合するプログラムが既にある場合を除いて、
最初はどういう機能がとか、画面が云々とかは不要。
必要だといわれたら付け足していけば良いはず。
読む側にとってどうでもよさそうな事は極力避ける事。
省2
587(1): 2008/05/09(金)16:21 AAS
>>586
入力、出力ってどういう意味ですか？
A4用紙一枚にまとめるのは変でしょうか？
588(1): 2008/05/09(金)16:40 AAS
>>587
入力も出力もないプログラムは役に立たないだろう
記述が必要十分なら一文字にまとまっていても構わないぞ
589: 2008/05/09(金)17:00 AAS
>>588
もしデータベースを扱うプログラムだったら、
どのようなデータを登録して（入力）、どのような形で表示するか（出力）
簡単に言えばこのような事でしょうか？
590: 2008/05/09(金)20:04 AAS
電卓のイメージなら簡単だろ？
ユーザーが入力して、プログラムがそれを計算する。（出力）
591: 2008/05/10(土)01:11 AAS
上司から言われたことの真の目的を明確にして、その目的を達成するためのプロセスや成果物を決めたらどうだろうか？
社会人の常識とかじゃなくて、目的から考えた方がよいのでは
592(2): 2008/05/10(土)10:46 AAS
クラスの仕様の概要って、どこまでが概要ですか？
593: 2008/05/10(土)10:52 AAS
>>592
クラス仕様の詳細じゃない部分
594: 2008/05/10(土)11:23 AAS
>>592
・そのクラスの責任範囲と全体の中での役割
・超簡単なサンプル使用例
・データの流れと関与する主要APIを図示したもの（ポイントとなるクラスの場合）
これが１ページで欲しい所。
595(1): 2008/05/26(月)16:40 AAS
doxygenについて質問したいのですが、専用スレが無いようなのでこちらでさせてください。
PC:Windows XP
コンパイル方法:Visual Studio 2005のコマンドプロンプト上で、下記の命令をする
make msvc
C:\doxygen1.5.5 に doxygen1.5.5.src.tar.gz を解凍した中身を置きました。
C:\doxygen1.5.5\src のソースをいじって、コンパイルしましたがエラーが出てしまいます。
エラー内容
----
link /NOLOGO /LIBPATH:..\lib /SUBSYSTEM:console /OUT:..\bin\doxygen.exe
@C:\DOCUME~1\AA\LOCALS~1\Temp\nm2E.tmp
省12
596(1): 2008/05/26(月)17:33 AAS
libiconvって書いてあるじゃん。
エラーメッセージぐらい読めるようになったら？
597: 2008/05/26(月)18:28 AAS
>>596
ありがとうございます。
iconv.lib,iconv.hがdoxygenのソース内に入っていたのでこれで良いのかと思っていました。
Libiconvをコンパイルしたものと差し替えたら、コンパイルが通過して下記ファイルが出来ました。
doxygen.exe
doxytag.exe
598: 2008/05/26(月)18:33 AAS
guest/guest
599(1): 2008/05/28(水)23:41 AAS
開発の人間なら仕様書を云々言う前に
ソース内のコメントをちゃんと書け！
と思う、インフラ屋は俺だけではないはず。
特にリリース後の修正箇所に対して正確な
コメントが書かれているソースが本当に少ない。
頼むから引数のコメントくらい、まともに書いてくれ・・・・
600: 2008/05/30(金)04:18 AAS
変数名自体を説明にするしかない
601: 2008/05/30(金)13:08 AAS
システムハンガリアンを止めて、アプリケーションハンガリアンにする。
602: 2008/05/31(土)00:23 AAS
>>599
> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。
これはコミットログやChangeLogの役目だろう
603(1): 2008/05/31(土)13:13 AAS
> これはコミットログやChangeLogの役目だろう
ソース内のロジックとコメントは分業してるってこと？
ロジックとそのコメント内容が一致してないから
障害対応してるときに頭からソースを読まなければ
ならないってこと。
そして、修正したPGはすでにいないことが多い・・・・
604: 2008/05/31(土)17:32 AAS
コメントとソースを同じくらい価値があるものだと考えるのはいいが
コメントとソースを同じように扱ってはいけないだろ
605: 2008/05/31(土)18:51 AAS
そこまでコメントに期待してないよ。
ただ最初にも書いたけど、表題部の
プログラム名や用途、引数説明すら
まともに書いてないソースが多すぎる
からカキコしただけだ
606: 2008/05/31(土)19:19 AAS
doxyの1.5.6でツリーが文字化けするのって俺だけ？
1.5.5平気なんだけど
607: 2008/05/31(土)21:19 AAS
４コマ漫画で８００ページの取扱い説明書
608(1): 2008/05/31(土)22:24 AAS
>>603
> 特にリリース後の修正箇所に対して正確な
> コメントが書かれているソースが本当に少ない。
これは 「こう修正しました」 っていうコメントのことでしょ？
それはまさにコミットログ等の役割
コードからは読み取れない 「こういう処理です」 っていうのがコメントの役割だと思う
609(2): 2008/06/01(日)01:34 AAS
>>608
"「こう修正しました」"は
ソース内の修正(変更)履歴のことを言ってる。
610(1): 2008/06/01(日)01:53 AAS
>>609
そりゃあSCMがない時代の苦肉の策でしょ
611(1): 2008/06/01(日)09:06 AAS
>>609
バージョン管理使おうぜ
612(2): 2008/06/01(日)11:47 AAS
>610,611
今、休出でVSS見てるけど、コミットログやChangeLogは存在しない。
各ソースのチェックインコメントは全部一緒で"○○○○更改に対する修正"・・・・
ほかに見るとこあれば教えてくれ。
（インフラ側で作ってる基盤モジュールのアップデート履歴のほうが
詳細に記載している。）
613: 2008/06/01(日)17:35 AAS
>>612
履歴を残そうという意識が作業者に無ければコミットログにも残るわけ無いだろ。
お前んとこのローカルな事情だな、それは。
で、一般的に履歴を残すんならどっちかというとコミットログのほうが適切という話。
614: 2008/06/01(日)17:43 AAS
>>612
コミットログはチェックインコメントと同じ意味
ツールが違うと用語が違う
チェックインコメントが全部一緒だと無意味だと感じませんか？
チェックインコメントは修正内容を記録するのにうってつけだと思いませんか？
615: 2008/06/01(日)17:49 AAS
ソースに履歴コメントされても探すのが大変だし。同時に変更したファイルの関連や前後関係も把握するのも正確に記載するのも困難。
コミットログならすぐ探し出せる。コメント漏れがあっても差分を見つけられる。
コミットログに情報がないというのは、結局コメントの入れ方、運用の問題でしょ。
616: 2008/06/01(日)19:27 AAS
ソースが動かないというのは、結局プログラムの書き方、プログラミングの問題でしょ
みたいな感じに見えた
617: 2008/06/02(月)15:25 AAS
【コメント】doxygen【コンソメ】
2chｽﾚ:tech
618: 2008/07/27(日)04:43 AAS
doxygenの話題は禁止
619: 2008/08/23(土)14:10 AAS
外部ﾘﾝｸ:www.hotdocument.net
じゃだめかな。
620: 2008/08/23(土)18:05 AAS
これはひどい
621: 2008/11/17(月)15:02 AAS
doxygen,hotdocument,visio
どれがいいだろうか・・・
C++Builder2007なんだけど。どれ対応してるかもまだ調べてないんだ。
とりあえず・・・探すか。
622(2): 2009/02/07(土)11:48 AAS
詳細仕様の中でBNFを使用したら「意味がわからん」と言っておこられましたorz
何か適当な代替え手段はないでしょうか？
# 何年ソフト屋やってんだ？ BNFくらい読めよ > 某メーカの糞 SE
623: 2009/02/07(土)12:29 AAS
アキバのチョムチョムでやけ酒の飲むしかないね。
624: 2009/02/07(土)12:32 AAS
知らないと読めないんだから確認しなかったお前が悪い
625(1): 2009/02/07(土)13:16 AAS
BNFの書き方が悪かったんじゃないの？
要所で適切な名前をつけて分割してあれば読みやすいし、
BNF知らなくても直感的にわかると思う。
逆に、１行でだらだら書かれたりすると、いくら正しくても読みづらい
626: 2009/02/07(土)14:43 AAS
学生「意味が分からない．」
先生「意味が分からない．」
627(1): 2009/02/07(土)17:25 AAS
構文の説明でもオートマトンで図示するのが多いかな
628: 2009/02/07(土)17:42 AAS
>>625
条件指定できる設定ファイル用なので、そんなに巨大なツリーじゃない
そもそも, BNF の読み方を知らないらしい
>>627
Pascal の構文定義に使ってある奴？ あれって、けっこう一般的なの？
つか、BNF と変わらないような気もするが…
大量の使用例を書くしかないのか？
629: 2009/02/07(土)18:58 AAS
BNFじゃなくてSEFで書かないとだめです
630: 2009/02/07(土)20:30 AAS
理解したいというなら教えてやれば言いと思うけど、単に
xxx *= yyy | xxx yyy
を
項 xxx は、単独の yyy または xxx に続く yyy によって定義されます。
とかの半分機械的な置換で済むかもよ。
631(1): 2009/02/07(土)22:55 AAS
>622
BNF云々というより、人との付き合い方の問題な気がする
TPOとか判ってないでしょ
他人のオナニー文書を読まされる側の立場にもなってみろ
632: 2009/02/08(日)01:39 AAS
>>631
書き手：「お前のオナニー用エロ文書を書かされる立場になってみろ」
読み手：「他人のオナニー文書を読まされる側の立場にもなってみろ」
不毛な・・・
633: 2009/02/08(日)01:52 AAS
言いたいことがわからない
634: 2009/03/07(土)12:45 AAS
仕様書はどっかの機関が音頭を取って規格化してほしいわ
635: 2009/03/07(土)21:27 AAS
フローチャートは全面禁止してほしい
636: 2009/03/07(土)21:52 AAS
ドキュメントって小説みたいなところがあるよな。
どんなに文字を尽くして書いても、相手の頭にすっと入ってイメージを
作れないと負け。
駄目なドキュメントって、たぶんすべて書いてあるんだろうけど
量ばかり多くてツマラン推理小説みたい。筋の5W1Hがさっぱり見えないで
筋書きを楽しむ以前に何がなんだかわからないオナニーみたいなやつ。
637: 2009/03/14(土)03:43 AAS
彼氏（彼女）のオナニー見ながらオナニー
見せ合いっこはｺｰﾌﾝする
638: 2009/04/10(金)18:21 AAS
あるある
639: 2009/04/12(日)14:23 AAS
俺様要求仕様書と俺様詳細設計書のガチンコ勝負！
640(1): 2009/06/13(土)08:57 AAS
質問させてください。
学習目的で小さなプロジェクトを立ち上げようと思っているのですが、
各種ドキュメント（基本設計、詳細設計、テスト仕様書等）の雛形、規格のようなものは
どこかで公開されていないのでしょうか？
IEEEって団体が作ったものがあるようですが
無料ですぐに手に入るものではないようです。
他にどこか有名な団体が作成したものがあるでしょうか。
できれば日本語が好ましいです。
よろしくお願いします m(__)m
641: 2009/06/15(月)11:53 AAS
俺みたいな底辺SEはプロジェクト終了と同時に傭兵のように各地に派遣されてるから
行く場所場所でドキュメントの定義やスコープ、はたまた名称まで違ってて毎回混乱・・。
その場所のしきたりに慣れるまでストレスを追わにゃぁならん。
プロジェクトの規模にもよるから当然ちゃ当然だが、ドキュメント類は
大まかな指針のようなものに従って書いてもらいたいし、書きたいわけだ。
どこかの学者様かスーパーＳＥ様あたりが統一規格のようなものを打ち出してくれて、
それが広まってくれれば助かるんだがな。
642: 2009/06/15(月)12:47 AAS
大丈夫、底辺SEがどんなに頑張っても既に採用されている仕様書のフォーマットが変わることはありえないから。
そもそも用語でさえベンダ間で互換性がないんだから、どうしようもないな。
643: 2009/06/15(月)16:25 AAS
ドキュメントは既存フォーマットを改良して作るのが一番てっとり早いわな。
であるならば、新規プロジェクトを起こす場合、最大公約数的な雛形となるべき指針が
存在してもいいはずだと思わんでもない。
ま、下請けが納品する場合はどうあがいても、大手のフォーマットを利用せざるを得んのだろうが・・。
ちょっと探してみたんだが
外部ﾘﾝｸ:www.hotdocument.net
↑あたりはなにかしらのフォーマットを利用したんだろうか？
644: 2009/06/15(月)19:02 AAS
何を持って良いドキュメントって言うんだ？
普通そこらに転がってるドキュメントって、
＊＊＊ このように、できてます！！！ ＊＊＊ が、書いてあるだけで
＊＊＊このように作らなければならない理由＊＊＊ が、書いてない。
＊＊＊もっと上の仕様書との連続性もない＊＊＊ 場合がほとんど。
なので、メンテナンスの役に立たない。
645: 2009/06/15(月)21:11 AAS
>>640
大手ベンダが専門の標準化チーム作ってフォーマットをガリガリつくってんのが現状。
派遣ソルジャーがデータ持ち出さない限り表にゃあ出てこねえよ。
646: 2009/06/16(火)06:58 AAS
IPAの発注者ビューガイドラインとかどうでしょう。
発注者視点ですが、開発者でも使えると思う。
647: 2009/06/16(火)14:37 AAS
これあたりは熟読すればいいんじゃなかろうか？
外部ﾘﾝｸ[htm]:www.sage-p.com
俺めんどくさいから目通してないがｗ
648: 2009/06/16(火)17:10 AAS
Naming Conventionとコメントだけ統一してればいいよ。
649: 2009/06/16(火)23:38 AAS
そもそも、小さなプロジェクトならドキュメントなんて必要ない。
上下前次1-新書関写板覧索設栞歴
ｽﾚ情報 赤ﾚｽ抽出 画像ﾚｽ抽出 歴の未読ｽﾚ AAｻﾑﾈｲﾙ
ぬこの手 ぬこTOP 1.108s*