アカウント名:
パスワード:
冒頭だけ読みましたが、これは初心者殺しのマニュアルですね。RMSは多数の罠を仕込んでいます。
1) 最初の罠: gitで公開されているファイルは GNU Texinfo 形式
あなたは git が使えますか? texi から html やpdfを生成できますか? この質問で何を聞かれているか理解できない人は、このマニュアルを読むことさえ出来ません。RMSこわい。
2) 次の罠: 最初のコードはフィボナッチ数を再帰処理で計算する例
いきなり再帰関数です。フィボナッチ数。スタック使って再帰を実行するぜ。メモリブロックの一部がスタックって呼ばれる領域なんだけど、C言語はそこを使って再帰を
> 知らない人は読んでも理解できない。> 知ってる人は読む必要がない。
ダメなマニュアルあるあるすぎる
技術書とかも、わかってから読むとわかるってのよくあるよね (´・ω・`)
ハード(デバイス)のマニュアルはみんなそう。「初見の人に分かり易く」書くつもりなんか絶対に無いんだろうな、っていつも思う。
デバイスのマニュアルは教科書じゃないし電気的な条件とか判りやすいじゃないですか(多分
謎のAPIのマニュアルだって分かりづらかったりするかも
多分、annoymouse coward (11178) と彼 #4322131 の言いたいことは「マニュアルは、分からない人が分かるように書くべし」って考えなんだろう。でもハードでは「マニュアルは、分かる人が分かるように書かれている」と。
「GNU C Intro and Reference Manual」とあるんだから、「Reference manual」を「指導者向けの参考資料」という意味で解釈するべきなんだよ。「manual」には「指導書」という意味があります。デバイスの manual は「*取扱*説明書」(製品仕様書)の意味です。手引きや教習という意味で解釈すべきではありません。「Intro」は、製品のデモンスト
デバイスのマニュアルの話を持ち出した#4322131です。#4322131はコメント先の「わかってから読むとわかる」に反応しただけなので、大元のGNU C 言語リファレンスマニュアルについてはコメントしません(そもそも読んでないし)。#4322131でちゃんと書きませんでしたが、問題にしたいのは電気的条件等ではなくソフトウェアインターフェースの説明です。#4323084のいう「API」がソフトウェアインターフェースのことだとしたら同意見と言うことでしょうか。デバイスのソフトウェアインターフェース自体がわかりにくいというか「素直じゃない」のは、そのデバイスの歴史的に最小限の改造で機能追加してきているので仕方がないかなと思います。分かりやすいインターフェースにするために回路の改造が増えて価格が上がることはユーザも望んでないでしょうし、過去のソフト資産との互換性も失われますし。だからこそ説明くらいはわかりやすく書けないものかと思うのです。ソフトウェアインターフェースの説明は電気的条件等と違って確立した記法が無いので文章でダラダラ書かれるのですが、本当に過不足なく書かれているか怪しく、実際に何パターンか試してみて初めて正しいパターンがわかるということもあります。まさに「わかってから読むと(間違ったことは書いてないことが)わかる」のです。「わかりやすく」書くという表現に語弊があったようです。「紛れの無いように」書いて欲しいものです。まあ、デバイスの設計者にとってはマニュアルを書くのは余技で本職ではないから仕方ないということなんでしょうが。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
身近な人の偉大さは半減する -- あるアレゲ人
これは無理ゲー (スコア:5, おもしろおかしい)
冒頭だけ読みましたが、これは初心者殺しのマニュアルですね。RMSは多数の罠を仕込んでいます。
1) 最初の罠: gitで公開されているファイルは GNU Texinfo 形式
あなたは git が使えますか? texi から html やpdfを生成できますか? この質問で何を聞かれているか理解できない人は、このマニュアルを読むことさえ出来ません。RMSこわい。
2) 次の罠: 最初のコードはフィボナッチ数を再帰処理で計算する例
いきなり再帰関数です。フィボナッチ数。スタック使って再帰を実行するぜ。メモリブロックの一部がスタックって呼ばれる領域なんだけど、C言語はそこを使って再帰を
Re: (スコア:0)
> 知らない人は読んでも理解できない。
> 知ってる人は読む必要がない。
ダメなマニュアルあるあるすぎる
Re: (スコア:0)
技術書とかも、わかってから読むとわかるってのよくあるよね (´・ω・`)
Re: (スコア:0)
ハード(デバイス)のマニュアルはみんなそう。
「初見の人に分かり易く」書くつもりなんか絶対に無いんだろうな、っていつも思う。
Re: (スコア:0)
デバイスのマニュアルは教科書じゃないし
電気的な条件とか判りやすいじゃないですか(多分
謎のAPIのマニュアルだって分かりづらかったりするかも
Re: (スコア:0)
多分、annoymouse coward (11178) と彼 #4322131 の言いたいことは「マニュアルは、分からない人が分かるように書くべし」って考えなんだろう。
でもハードでは「マニュアルは、分かる人が分かるように書かれている」と。
「GNU C Intro and Reference Manual」とあるんだから、「Reference manual」を「指導者向けの参考資料」という意味で解釈するべきなんだよ。「manual」には「指導書」という意味があります。デバイスの manual は「*取扱*説明書」(製品仕様書)の意味です。手引きや教習という意味で解釈すべきではありません。
「Intro」は、製品のデモンスト
Re:これは無理ゲー (スコア:0)
デバイスのマニュアルの話を持ち出した#4322131です。
#4322131はコメント先の「わかってから読むとわかる」に反応しただけなので、大元のGNU C 言語リファレンスマニュアルについてはコメントしません(そもそも読んでないし)。
#4322131でちゃんと書きませんでしたが、問題にしたいのは電気的条件等ではなくソフトウェアインターフェースの説明です。
#4323084のいう「API」がソフトウェアインターフェースのことだとしたら同意見と言うことでしょうか。
デバイスのソフトウェアインターフェース自体がわかりにくいというか「素直じゃない」のは、
そのデバイスの歴史的に最小限の改造で機能追加してきているので仕方がないかなと思います。
分かりやすいインターフェースにするために回路の改造が増えて価格が上がることはユーザも望んでないでしょうし、
過去のソフト資産との互換性も失われますし。
だからこそ説明くらいはわかりやすく書けないものかと思うのです。
ソフトウェアインターフェースの説明は電気的条件等と違って確立した記法が無いので文章でダラダラ書かれるのですが、
本当に過不足なく書かれているか怪しく、実際に何パターンか試してみて初めて正しいパターンがわかるということもあります。
まさに「わかってから読むと(間違ったことは書いてないことが)わかる」のです。
「わかりやすく」書くという表現に語弊があったようです。「紛れの無いように」書いて欲しいものです。
まあ、デバイスの設計者にとってはマニュアルを書くのは余技で本職ではないから仕方ないということなんでしょうが。