良いドキュメント・マニュアル・仕様書を書くスレ
■ このスレッドは過去ログ倉庫に格納されています
0001デフォルトの名無しさん
NGNGドキュメントを書ける自信はあるか？
仕事で納品したり、他人に見せるプログラムとして公開するつもりなら、
マニュアルや、仕様書などのドキュメントを書く機会は必ずある。
プログラムとドキュメントはとても関係が深い。ドキュメントが整っていない
プログラムなど、ゴミと同じ。それに、ただ書けばいいって物でもない。
ドキュメントがゴミ程の役にも立たなければ、結局それはゴミなのだ。
だらだらと書いた意味不明な文章を他人に見られるのも恥ずかしいよな？
いわばドキュメントを書く技術はプログラマの必須スキルの１つなのだが、
実際は、下手糞なドキュメントが蔓延っている。(これはGNU製に多い)
読んでも無駄とか、書いても無駄とか思ってる奴、その考えを改めろ。
プログラムに対するドキュメントを、ちゃんとした１作品として、
後世に残せるよう努力すべきだろう。
今一度問う。
おまえら、わかりやすく的確なドキュメントを書ける自信はあるか？
0153デフォルトの名無しさん
NGNG0154デフォルトの名無しさん
NGNG今までマニュアルや仕様書を（良い悪いに関わらず）読んできた経験に基づいて決める。
どこでも見かけるルールには従う。
あ、このルールいいな、と思ったものは取り入れてみる。
このルールだめじゃん、と思ったものは自分ではそうならないように気をつける。
ま、毒にも薬にもならん意見だな。
「ドキュメント」「標準」とかをキーに検索すれば？
0155デフォルトの名無しさん
NGNG先例でいい奴とかまねしてるが、業界として共通の表現とかって
どっかないんかな…
0156デフォルトの名無しさん
NGNG0157デフォルトの名無しさん
NGNG0158デフォルトの名無しさん
NGNG0159デフォルトの名無しさん
NGNG0160デフォルトの名無しさん
NGNG0161デフォルトの名無しさん
NGNGINPUT_FILTER使えば？
0162デフォルトの名無しさん
NGNGソースがドキュメント
0163デフォルトの名無しさん
NGNG0164デフォルトの名無しさん
NGNG0165デフォルトの名無しさん
NGNG俺のソースはきれいだと腐ったソースで自分に酔ってる厨と同じ。
0166デフォルトの名無しさん
NGNG（プロジェクトが）
0167デフォルトの名無しさん
NGNG0168Ruby!!!!!!!!!!!!!!
NGNGおまえらひれ伏せ。
0169デフォルトの名無しさん
NGNGドキュメントはソースだけで十分です。
#endif
0170デフォルトの名無しさん
NGNG○ドキュメントはソースだけしかありません。
0171162==163
NGNGいや、
おれが、ドキュメント書かないわけじゃないよ。
一応気を使ってdoxygen対応で書いてるぜ。
で、
わかりにくいドキュメント見るぐらいなら、ソース見るって感じ。
ドキュメント読んで信じて、騙されるぐらいなら
ソースを読んだ方が正確。時間もさほど変わらない。←これが俺ぐらいのレベル
ソースが汚い奴のドキュメントは、
やっぱりわかりにくい罠ってのもある。
一応、EffectiveC++レベル以上のその系統の書籍を数冊読んでるし、
汚いソース何個も見てきたので
ある程度の読みやすいソース書く自信あるぜ。
そういう本読んでない初心者ちゃんにはきついかも。
0172デフォルトの名無しさん
NGNGソース自体が読みやすいとか読みにくいとは全く別問題だし。
自分のソースにはバグは一切無いとか、
仕様のためのコードなのか、高速化のためのコードなのか、単にダメっぽいコードなのか、
みたいのを誰が見ても一目瞭然で区別できるとかいうなら話は別だが。
0173デフォルトの名無しさん
NGNG0174デフォルトの名無しさん
NGNG0175デフォルトの名無しさん
NGNG0176デフォルトの名無しさん
NGNG0177デフォルトの名無しさん
NGNG*.hにコメント書くよりも*.cppに書いたほうが良い、というのは理解した。
(そりゃそーだわな)
でも、DLLなどのバイナリライブラリでソース見せたくないときは、
*.hに書くしかないような気がする。
*.cppに書いてあったコメントが、あたかも*.hに書いてあったように
Doxygenできる方法ってあるの？
それともローテクにリリース寸前でコメントを*.hにコピペするんか？
0178デフォルトの名無しさん
NGNGまだまだ使い始めだからわかってないのかもしれないが、
要は、ソースが丸見えになるのがいやなのだ。
ソースを隠すオプションが探し切れていないだけなのかもしれん。
0179デフォルトの名無しさん
NGNGDoxygenした結果はcppに書いてあろうがhに書いてあろうが同じだと思うが。
ソース隠すオプションはある。
0180デフォルトの名無しさん
NGNGWindowsならDoxyWizard使うと楽チン。
0181デフォルトの名無しさん
NGNGすまんかった、いろいろ試してみたらソース隠せたよ。
DoxyWizardは知らんかった、ちょっとさわってみる。
0182デフォルトの名無しさん
NGNG0183ライブラリアン
NGNG書くものじゃないの。仕様書とか検査成績書とか。
プロはドキュメントを書いている時点で情報不足や矛盾が
わかるのでしょう。
プログラムを作ってからドキュメントを作るのは
最低だな。ゲーム少年の域をこえてないよ。
0184デフォルトの名無しさん
NGNG0185デフォルトの名無しさん
NGNG0186デフォルトの名無しさん
NGNG0187デフォルトの名無しさん
NGNG0188デフォルトの名無しさん
NGNGおいらのとこでは、プログラマが書くのは保守ドキュメントのほうが多い。
そうするとあとで書いたほうがいい。
同時にかくのはもっといい。
仕様書、成績書は別の人間が書く。
同じ人間がかくってことは零細？
0189デフォルトの名無しさん
NGNG0190デフォルトの名無しさん
NGNG書く順番の話をしているのでは
ということは188は読解力ゼロ？
0191デフォルトの名無しさん
NGNG0192188
NGNGプログラマの文書は保守文書が多かろうから
あとか同時に書くほうがいいし、あとが駄目とは
言い切れないんじゃないのということが言いたかった
ですよ。
んで、矛盾を見つかる仕様書は別の人が
書くだろうからそれで、非プロとはいかがなものかと。
>>189
悪くないけど大変ですね。
0193デフォルトの名無しさん
05/02/08 23:36:23doxygenのLaTeX出力は鬼門だな
ttp://www.atmarkit.co.jp/bbs/phpBB/viewtopic.php?topic=8354&forum=3&2
この辺のでｻﾝﾌﾟﾙは上手く逝ったが、漏れのソースだとｲﾋけ杉
0194デフォルトの名無しさん
05/02/09 15:13:57概念モデルで。
0195デフォルトの名無しさん
2005/04/09(土) 19:20:510196デフォルトの名無しさん
2005/05/08(日) 01:04:55int main(void){
char s[BUFSIZE]; //!汎用バッファ
↑こんなやつ。
0197デフォルトの名無しさん
2005/05/08(日) 01:11:53ローカル変数を廃止して、全部グローバルにすればOK？
0198デフォルトの名無しさん
2005/05/08(日) 01:14:38ｗｗｗｗｗｗｗｗｗｗｗｗおｋｗｗｗうはっｗｗｗ
うぇｗｗｗ
おｋｗｗｗっっおｋｗｗｗｗｗｗｗｗｗｗ
ｗｗｗうぇｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ
0199デフォルトの名無しさん
2005/05/08(日) 01:28:10おｋｗｗｗっっおｋｗｗｗっうぇうぇｗｗｗ
うはっｗｗｗ
っｗｗｗｗｗｗｗｗｗｗｗｗ
っうぇｗｗｗｗｗｗ
うはっｗｗｗっうぇｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ
0200デフォルトの名無しさん
2005/05/08(日) 23:37:07そんなもの出力する必要あるの？
0201デフォルトの名無しさん
2005/05/08(日) 23:48:31変数のドキュメントは必要でしょー
0202デフォルトの名無しさん
2005/05/08(日) 23:50:12doxygenって、関数やクラスのインタフェースを記述するためのものじゃないの？
0203デフォルトの名無しさん
2005/05/09(月) 11:15:06きめつけ：(･Ａ･)ｲｸﾅｲ
0204デフォルトの名無しさん
2005/05/09(月) 11:27:33ローカル変数ってのは隠蔽されるべきものなので、
皆が読むドキュメントには書くべきではないと思われ。
実装者とか保守する人用に注意書き程度にコメント書くなら構わんと思うけど。
0205デフォルトの名無しさん
2005/05/09(月) 11:54:51じつわ
ぜんぶmadeinusa
なので
それを
にほんごにするときに∞∴♂♀℃￥＄¢£％＃＆＊＠§☆
0206デフォルトの名無しさん
2005/05/09(月) 12:07:04おｋｗｗｗうはっｗｗｗｗｗｗおｋｗｗｗ
ｗｗｗｗｗｗｗｗｗｗｗｗ
っうぇ
ｗｗｗｗｗｗｗｗｗｗｗｗ
うはっｗｗｗおｋｗｗｗｗｗｗｗｗｗｗｗｗｗっうぇ
0207デフォルトの名無しさん
2005/05/10(火) 00:19:54保守用ドキュメントを作成し
0208デフォルトの名無しさん
2005/05/10(火) 02:08:45普通は意味無いので
0209デフォルトの名無しさん
2005/05/10(火) 02:30:03ｗｗｗｗｗｗｗｗｗｗｗｗｗうはっｗｗｗｗｗｗｗｗ
ｗｗｗっｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ
おｋｗｗｗ
うはっｗｗｗｗｗｗうぇｗｗｗ
ｗｗｗｗｗｗｗｗｗｗｗｗ
0210デフォルトの名無しさん
2005/05/10(火) 03:33:47おｋｗｗｗうぇｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗうはっｗｗｗ
うぇｗｗｗｗｗうはっｗｗｗｗｗｗｗｗｗｗｗｗｗｗｗ
ｗｗｗｗｗｗｗｗｗｗうはっｗｗｗｗｗｗうぇｗｗｗ
0211デフォルトの名無しさん
2005/05/11(水) 08:37:360212デフォルトの名無しさん
2005/05/11(水) 20:58:440213デフォルトの名無しさん
2005/05/12(木) 09:26:540214デフォルトの名無しさん
2005/05/12(木) 22:50:480215デフォルトの名無しさん
2005/05/13(金) 09:19:260216デフォルトの名無しさん
2005/05/13(金) 18:14:500217デフォルトの名無しさん
2005/05/15(日) 00:34:54ソースのひな形つくってdoxygenか？
なんか綺麗な方法ないか探し中の俺に教れろ。
0218デフォルトの名無しさん
2005/05/15(日) 01:00:180219デフォルトの名無しさん
2005/05/17(火) 01:13:370220デフォルトの名無しさん
2005/06/07(火) 00:18:400221デフォルトの名無しさん
2005/06/12(日) 01:55:490222デフォルトの名無しさん
2005/06/12(日) 12:15:26つーか、いねーよそんな奴(ﾌﾟｹﾞﾜﾛｳｽ
0223デフォルトの名無しさん
2005/06/12(日) 14:45:09目的はdoxygenにリンクさせて、一括管理しようと思ってます。（名づけて一元化）
WORDで作るとhtmlじゃなくhtmってなって、WORDで開いて.docにも変換可能です
質問はhtmって一般常識として普及しているのかどうかです
みなさんは、仕様を書くソフト（拡張子）は何を使ってますか？
0224デフォルトの名無しさん
2005/06/12(日) 14:51:50テキストで管理して変換変換
.txt→.htm→.pdf と
0225デフォルトの名無しさん
2005/06/12(日) 15:10:03なるほど、テキスト最強ですな。
でもページ上でリンクしたいから、テキスト厳しいかも。
変な表とか入れずに、互換性上げるのには気をつけてます。
0226デフォルトの名無しさん
2005/06/12(日) 15:29:56htmlをWORDで作るってのが個人的には好きではないが。
htmlは電子文書としては最強の一つだと思ってるよ。PDFよかぜんぜん好き。
仕様書は紙で出してナンボと思ってる古い業界体質も残ってるから
ウケはあまりよくないかも知れないけどね。
0227デフォルトの名無しさん
2005/06/12(日) 18:54:41どうせならもっと徹底して、テキストを完全に分離して欲しかったなぁ
テキスト側はもう生txtそのままでさ、
スタイルシート側は、面倒でも行で指定する感じ
実際は簡単なツールで補えば、行指定やテキスト変更も、手間でも無いだろうし
0228デフォルトの名無しさん
2005/06/12(日) 19:41:15行指定は面倒すぎだろ
あと、その概念はWord文書みたいだ
0229デフォルトの名無しさん
2005/06/12(日) 20:26:40確かに両方用意しないと行けない場合に便利だな。
頭の固いおっさん向けに、紙に印刷する必要がある時とか。
0230デフォルトの名無しさん
2005/06/12(日) 23:17:560231デフォルトの名無しさん
2005/06/13(月) 01:14:18自分ならdoxygenでRTFで出力してpdfに変換して添付ファイルにするか、
WORDでRTFを開いてDOCに保存しなおすか。
RTFだとリンクはそのまま残るし、ドキュメントとしてもそれなりに
綺麗に出力されるからお勧め。一度試してみれ。
0232デフォルトの名無しさん
2005/06/13(月) 01:22:28それでお客に納品するの？
おいらは、Visioやパワーポイントも使わないようにしてるけど
打ち合わせ資料で使うときあるけど、最終的にはエクセルで書き直す事になる
0234デフォルトの名無しさん
2005/06/13(月) 03:52:03XMLに対応したコンパイラ
0235デフォルトの名無しさん
2005/06/13(月) 11:35:27XMLってマジで言ってますか？
0236デフォルトの名無しさん
2005/06/13(月) 20:30:41XSLT使えばどうにでもなる気がする
0237デフォルトの名無しさん
2005/06/14(火) 13:26:23「文芸的プログラミング」(literary programming)
つーのを提唱して WEB つーシステムを開発したよね
それやりゃいいんだろ
0238デフォルトの名無しさん
2005/06/14(火) 21:01:39,r" .,/i、 .ﾍ, ｀ヽ、
､" ./::::::i, /ヽ l..:::i, . '、
/ .,/:::::::::::i /.,:::l i::::::::i 、 ヽ
/ .,、.,i:::::::::::::::i, /:::::::::v,,:::::::::l, ,li i
│ /:l./::::i::::|l::::::V,:::::::/i:::::::ﾍ::::::V::l, . | ,.,..,,.,..､、
| ./:::l:::::::l-i:|-!::::::::::::::/ 'l:::/--l::::::;;;;l ..ﾚ'"´
l .i::::::::::::l-i-'｡.ヽ::::::::/ ´l/-｡､i:::::::::::! ..i 可 理
'!l:::::::: ﾍl |::::::l` i:::::/ ｲ::::::| ,!/::::::. i | 能 論
i::::/i::::l,｀ ￣｀ Ｖ ￣ i::::i::::./ な 上
V l::::l, J /::::i "i/ ん は
ﾞl:::＼ ＿＿ ./l:::/ で
'!/ ヽ._ ヽ ﾉ ,／" iv す
＿.|｀ヽ- -イ|＿ ＜ ﾟ
,,､ノ;;;;;;;||||| |||||;;;;;;;ヽ.｀!
SmartDocみたいな使えないものになるのが落ち
0239デフォルトの名無しさん
2005/06/26(日) 01:01:12基本設計書からすべてExcelだ（´･ω･`）
確かに図を書くのがラクだけど・・・
0240デフォルトの名無しさん
2005/06/26(日) 17:00:24Wordでもなんでもいいと思う
0241デフォルトの名無しさん
2005/06/26(日) 17:48:03おれ、ワードは線がずれたら直せないんだよ。
0242デフォルトの名無しさん
2005/06/26(日) 17:52:50根性、根性、ど根性
ちなみにIMEだと ど根性 で一単語になってる
0243デフォルトの名無しさん
2005/06/27(月) 03:53:010244デフォルトの名無しさん
2005/06/27(月) 12:39:170245デフォルトの名無しさん
2005/06/28(火) 11:06:46FEPって方が通りがよかった。
だからついMS-IMEの事をIMEといってしまうま。
0246デフォルトの名無しさん
2005/08/21(日) 20:15:270247デフォルトの名無しさん
2005/08/22(月) 09:31:21俺の場合
図や表、文をまぜこみの仕様書である程度見栄えも気にする場合は、
OpenOfficeOrg2.0Betaを使っている。
Wordは俺は受け付けることができなかったが、Oooはなんとか好きになれそう。
htmlでやっているって言う人は、テキストエディタでごりごり書いているのだろうか？
ま、それが一番書きやすいのだが、そろそろhtmlエディタで良いのが出てきてほしいなあ。
0248デフォルトの名無しさん
2005/08/22(月) 19:05:24Wordは俺のUIと合わなかった
0249デフォルトの名無しさん
2005/08/27(土) 15:18:42挙動不審な事が多いし良く落ちるがドキュメントやマニュアルを書くのにはやっぱ
エクセルよりワードだな。
0250デフォルトの名無しさん
2005/09/03(土) 13:55:02プログラマのためのワード講座
みたいなスレを立ててみようか
使いにくいと文句をいっている人は
例えるなら秀丸でVC++のソース編集してるようなもので
きちんと環境構築と突然死への備えを整えれば
VisualStudioなみの便利さを手に入れることはできる
0251デフォルトの名無しさん
2005/09/10(土) 01:05:560252デフォルトの名無しさん
2005/09/10(土) 04:56:03Windowsでエクセル（ ﾟдﾟ）ﾎﾟｶｰﾝ
社内通達がエクセルで回って来た事もある。本文無しで添付ファイル
があるだけという、思わずゴミ箱に放りそうになったぞ。
それはそれとして、前に文章作成なのに何故エクセル？という問いを
投げてみたんだが、エクセルで何の問題がある？と聞き返されて有耶
無耶になった。
ワードを使えば云々と言えるほど、俺はオフィスツール知らんからな。
て言うか、正直エクセルも線の引き方と文字の属性変更くらいしか知
らんのだけどねorz
誰もが納得するワードの利点とかあるなら聞きたい＞250
■ このスレッドは過去ログ倉庫に格納されています