[debian-users:10310] Re: How to Write Doccuments ( Re: Re: Afterstep 1.0 日本語メニューにできない )

[Ryuichi Arafune <arafune@xxxxxxxxxxxxxxxxxxxxxxxxx>]

荒船です．
えええと．
From: Masamichi Goudge <mguuji@xxxxxxxxxxxxxxxxx>
Subject: [debian-users:10288] Re: How to Write Doccuments ( Re:  Re: Afterstep 1.0  日本語メニューにできない  )
Date: Thu, 26 Nov 1998 17:44:29 +0900
Message-ID: <199811260844.RAA06250@xxxxxxxxxxxxxxxxx>

mguuji> Message-ID<19981126154014X.arafune@xxxxxxxxxxxxxxxxxxxxxxxxx>において
mguuji> Ryuichi Arafune <arafune@xxxxxxxxxxxxxxxxxxxxxxxxx>さん曰く:
mguuji> 
mguuji> > ほとんど Linux にも ましてや Debian にも関係なくなっては来ていますが
mguuji> 
mguuji> JFあたりに ドキュメントの書き方に関するドキュメントはありました
mguuji> でしょうか? そうしたドキュメントを生成するための有意義な問題提起に
mguuji> なれば幸いだと思います。
ま，幸いかもしれませんが，Unix (Linux) は
	問題提起の量＞＞解決された問題
なんで，ここらへんが潮時かもしれません．
mguuji> 
mguuji> > 別物ですか？ 私はちっとも別物ではないと思いますが．
mguuji> 
mguuji> それでしたら、優秀な論文を書ける人は 皆 寺田寅彦なり 渡辺淳一/加賀乙彦/
mguuji> 北杜夫 になっていると私は思います。
no 
ここが，いわゆる小説，エッセイ等(ま，いわゆる"文学"ってやつ)と，
論文およびマニュアル(JFだってLDPだって広い意味ではマニュアルでしょ
う．)との違いです．
　感動させる文を書く必要性 ＜＜　必要なことを確実に読み手に伝える必要性
ということです．

mguuji> > 結局のところ，
mguuji> > 	"読者の知識を想定し，一意にしかとれないような文章を書く"
mguuji> > ことが，どちらの場合にも重要なのでは？
mguuji> > このとき必要なのは
mguuji> > 	伝えたいことについての完全な理解
mguuji> > です．医学系の論文ってのは(勿論)読んだことないんですが(私は物
mguuji> > 性屋さん)この点は変わらないんじゃないですか？
mguuji> 
mguuji> その伝えたいことを伝えるために 閾値をどのあたりに設定されていますか?
mguuji> 物理系(でいいんですよね?)も 相当論文に対する評価が厳しい社会とうかがって
mguuji> いますが、専門傾向が強い雑誌に載せようとする場合、私は閾値を上げて、
mguuji> 「わからんやつは わからんでえぇ」というスタンスで書きます。あとはレフリー
mguuji> との勝負、と。
mguuji> # って CellやNew England Journal of MedicineのようなGeneralな雑誌に投稿を
mguuji> # 目指したことはありませんが....

それだと私はまず，教授のチェックではねられますね．
基本的に物理学は Universal な方法で単純化できる問題をとりあげる
ので，物理学者ならだれでもわかるように書くというのが根本的な姿勢
です． Maxwell 方程式を説明するようなことはしませんけど．

mguuji> 一方 ネットワーク/WWWで公開し、Slackware UserもDebian Userも読むような
mguuji> ドキュメントを書こうとする場合には Slackware特有のcommand, Debian固有の
mguuji> commandや環境に留意して、時には「これはDebianでの話です」や「私のSystem
mguuji> には 以下のような Pkgがinstallされており、~/.bashrc は.... , ~/.xsession
mguuji> は こうなっています」と 冒頭の方で明記する必要は無いでしょうか。
mguuji> 私はあると感じているので、自分が書くドキュメントでは そうしていました。
mguuji> # 今はお見せできないのが残念ですが.... f03dec.med.nihon-u.ac.jpが
mguuji> # 動いておらず....

そこは書く人のポリシーかもしれません．私も書けるものなら書いた方
がいいと思います．

ただ．．．
 	Slackware 固有といっても，結構 Debian に応用できてしまっ
たりすることがあるし．使っているときに Slackware と Debian の
明確な違いをみつけるのは，ディレクトリ構造ぐらいでしょうか．

この点を考えると， 
	Debian での話です．でも他の Distribution でも応用できるかもしれません．
と書くといいかもしれません．

mguuji> 最近まで 日経系のWWWで連載を持たせて頂いていましたが(残念ながらLinuxには
mguuji> 触れられませんでした)、MacOS 8 User と 漢字Talk7.x Userの双方に配慮した
mguuji> ドキュメントを書くのは 非常に骨が折れました。MS系のOSとMacOSに公平に
mguuji> 配慮しながら書く事も苦労しましたけど....

mguuji> ちょっと私が神経質過ぎる嫌いもあるかもしれませんが、そうでしたらどうか
mguuji> 御指摘下さい。

	<snip>

mguuji> # ぁぁぁ....書かないと.... > 論文

 わたしゃいまデータそのものが無い 困ったもんです．

Research Institute of Electrical Communication
Tohoku University
Dr. Ryuichi Arafune
arafune@xxxxxxxxxxxxxxxxxxxxxxxxx