FOSSのドキュメントが残念な状態で知りたいことがわからなかったら、どうやって解決する？ 111
ストーリー by headless
残念 部門より
残念 部門より
本家/.「Ask Slashdot: What To Do About the Sorry State of FOSS Documentation?」より
何年も前から趣味ではパソコンをあまり使わなくなっていたが、再開することにして驚いたのはオープンソースプロジェクトのドキュメントが変わっていないことだ。ソフトウェアはこの10年で大きく変化したが、ドキュメントは変化に追い付いていない。私が探しているものの多くはずっと前のバージョン用のものであったり、何年も前に私が趣味でパソコンを使っていた頃とまったく同じものであったりもする。たとえばUbuntu 14.04でLightDMを使用する場合、設定ファイルの構造がすべて変更されているにもかかわらず、高度な設定の説明は以前のバージョンのUbuntu用のままで、最新リリースには対応していない。実際にいくつかの機能を設定するのは10年前よりも難しくなっている。TLDPは10年近く古いものになっており、ディストリビューションが断片化しているためにあるディストリビューションに適用可能な回答が他のディストリビューションに適用できない例も増えている。特定のプロジェクト専門のWebフォーラムであっても、回答のない質問であふれ、質問とは無関係なディスカッションになってしまったり、「ドキュメントを読め」といった回答で終わってしまうこともある。FOSSの高度な設定などについて知りたいときは、どこで調べるといいのだろうか。
ソースから (スコア:2, 興味深い)
開発者が書かないでいる以上は、だれかがソースから解読してドキュメントを起こすしかないんだろうなあ。
読めても書けない人はそういう貢献もあるねってことで。
Re:ソースから (スコア:3, 興味深い)
ソース見れば実装はわかるけど、その背景や考え方がわからなかったりすることも多いんだよね。
「この機能は旧バージョンとの互換のためのもので今後廃止される予定である。そのため、今後は新しい機能を使うべきである」、とか。
Re:ソースから (スコア:1)
人のコードを触る業務が多いのですが、「背景の考え方」ってのが一番重要だと思ったり。
実装されているコードってのは、やろうとしている（いた）ことの一側面を記述しているに過ぎないと思いますです。
Re:ソースから (スコア:2, すばらしい洞察)
すごく賛同します
既存のソースコードからドキュメントを起こすという作業をしたことがあります
そのまま「こういう入力があればこういう動きをする」という部分は難なく書けるのですが
「なぜその動きをするのか」は推測するしかないんですね
# で，とりあえず推測でテキトーな理由をでっち上げてお茶を濁すしかないんです．．．
Re:ソースから (スコア:1)
そのコメントが「こう動く」ってだけの内容ではなく、「○○と考えたので、□□のパターンで実装した」とかだと非常に助かる。
Re:ソースから (スコア:2, 興味深い)
そして調べた結果をもとに簡単に設定するコマンドや設定画面作ると。
Re:ソースから (スコア:1)
問題は, ソースを読むためにはしばしば(というより殆どの場合かな?), 書いた人と同等以上の技量が必要になるってことでしょうか.
Re: (スコア:0)
そう言いながら食い散らかし続けて10年という事ですね・・・
Re:ソースから (スコア:4, 興味深い)
昔から言われ続けているオープンソースの欠点の一つだもんね。
みなボランティアでやると、各々やりたい事しかしない。面倒くさくてつまらないものは放って置かれるまま。
Re:ソースから (スコア:1)
＞企業がフルタイムで開発者を雇用しているOSSも少なくないのに現実のドキュメントがプアなのはなんでだろうね。
プロプライエタリな商用製品（しかも高額）ならドキュメントがリッチだとでも？
商用製品で問題にならないのは、販売元に直接問い合わせできるからに過ぎないですよ。
Re:ソースから (スコア:1)
ボランティア活動を使われる側としても、使う側としてもやった事がありますが、
ボランティア活動って、使われる側の希望をそれほど重視しないんですよね。
「何か貢献したい」という気持ちは大事にしつつも、何をするかは現場監督に任せるのが重要だったりする。
災害後の後片付けなんかをやったことがあれば分かるけど、使われる側は兵隊に徹しないと全然捗らないんです。
使う側の役割は、みんなに心地よく兵隊に徹してもらって作業を進めてもらう事だったりします。
FOSSの場合、そういう現場監督がなかなか存在しにくいところが、作業の方向性を決めにくい要因で、
確かに欠点ではあるのですが、じゃあ実装者が足りているからお前はドキュメントを書けなんて、
言ってくるFOSSプロジェクトなんてクソですからね。
FOSSは義勇兵による活動というより、ならず者の寄せ集めという雰囲気が近いと思います。
Re: (スコア:0)
コードは小説より面白いらしいからな。
通勤電車のひと時、スマホでコードリーディングしながらニヤニヤするのも一興か。
Re:ソースから (スコア:2, 興味深い)
そんなんめっちゃストレスたまるだけだわ。
ソース読むときはファイル内、フィル間で、あちらに飛んだりこちらに飛んだり又戻ったり、変数や関数を検索したり。
複数ウィンドウが開ける大画面とキーボードが無けりゃやってられん。
電車で読むときは、紙に縮小印刷して持っていく。行き戻りしやすいし、複数のページを同時に眺められる。
検索が出来ないのが残念だが。
Re:ソースから (スコア:3, すばらしい洞察)
ドキュメントと一言で扱われることが多いけど、階層や想定読者で違うよね。
このコメント [srad.jp]で言われているような、ポリシーや方針みたいな
大雑把なものから、動作オプションの影響範囲と差、さらに細かくは
関数の引数の意味、みたいなものまで。
ドキュメントを出せ、は「俺が知りたいことが 1ページで書いてある資料をだせ」なことも
多くて、結局 google だったりする。 （私はお前のおかあさんじゃない）
Re:ソースから (スコア:2)
Re:ソースから (スコア:1)
あれみても結局「スタートはどこ？」と放り出される感が半端ない。
http://www.cryptopp.com/docs/ref/ [cryptopp.com]
いや、あるだけいいんだけど。。
結局はテストコードとか、実装を追うことに。
Re:ソースから (スコア:1)
こういうアプローチは他コメント [srad.jp]のtex のシステム [wikipedia.org]の話も
あるけど、別ドキュメントを生成するんばかりでなくて、そのまま printf() で出力すれば、
printf() で出力できる形に exe に取り込んでくれれば いいんでないか？
時代が変わってメモリもHDDも安くなったんだから、
--help とか --version で簡単に説明が得られるやりかたの伸張として、
--source とやるとソースが出てくる、--documents でドキュメントが
出てくる、なんてのもありだと思うが。
日本語マニュアルも信用ならんしなぁ (スコア:2, 興味深い)
バージョンが古すぎて、新しいオプションが反映されていない、というmanページが多い
Re:日本語マニュアルも信用ならんしなぁ (スコア:1)
物によっては、本家の翻訳にオリジナルの記事が混じってて、更に翻訳部分が古かったりするとほんと混乱の元。
最低限、本家翻訳と日本オリジナルの区別や、翻訳がどの程度古いか明記して欲しい。
Re: (スコア:0)
あのApacheでさえ、日本語版ドキュメントがずっと変わっていないのに最新バージョンのドキュメントにそのままなっているらしいです。もっとも広く使われているものでこれですから。2.2と2.4って結構違うのに…
耳が痛い。。 (スコア:2, 興味深い)
大変申し訳ございません・・・・(某ディストリビューションの中の人)
逆に考えるんだ (スコア:2, すばらしい洞察)
ドキュメントが充実しているプロダクトを中心に選ぶんだと。
ドキュメントが充実 → 人気があって利用者数も多い → 機能改善も早く、将来性がある。
という正の相関もあるかもしれんしな。
Re:逆に考えるんだ (スコア:1)
例に上げられているXDMCPのドキュメントが極端に古いのは、
設定が簡単なVNC [wikipedia.org]やX11向けのＲＤＰ実装のXRDP [xrdp.org]にユーザーが移ったからかと。
Re:逆に考えるんだ (スコア:1)
ちょうど昨日までフォントとか作っていた [github.com]のですが、
FontForgeの日本語訳ページは「そもそもフォントとは〜」から始める親切さでした。
このページがなかったらフォント作ろうとは思わなかったし、諦めていたと思う。
(とはいえ訳されていない部分は確かにあるようで、未約部分があると思っていなかった日本語ページより長い英語版ページを見つけて、びっくりすることはある)
行間を読む (スコア:2)
ソースで動作は読めても、そこに至る過程は読めないからなかなか難しい
まぁ (スコア:1)
ArchWikiかなぁ。
使用者(pgとしては) (スコア:1)
Stackoverflowにだいたいの疑問の答えは乗っとるので助かる
「これでダメなんだが？」
「こうじゃね？」
「センキュー」
あの軽いノリがよろしい
浦島太郎 (スコア:1)
>私が探しているものの多くはずっと前のバージョン用のものであったり、何年も前に私が趣味でパソコンを使っていた頃とまったく同じものであったりもする。
何年も前の知識で検索していたとしたら、そりゃ昔の情報しか出てこない。
新しいテクノロジーを学びましょう！
（もちろん昔の知識・技術が現代でも通用するのなら、それは素晴らしいことだ。）
>実際にいくつかの機能を設定するのは10年前よりも難しくなっている。
ドンマイ
>「ドキュメントを読め」といった回答で終わってしまうこともある。FOSSの高度な設定などについて知りたいときは、どこで調べるといいのだろうか。
(1) 使っているディストリビューションの文書
(2) /usr/share/doc 以下
(3) http://www.freedesktop.org/wiki/Software/LightDM/ [freedesktop.org]
特に Configuration に書いてある、設定ファイルの配置規則について
(4) http://bazaar.launchpad.net/~lightdm-team/lightdm/trunk/view/head:/dat... [launchpad.net]
設定ファイルに書いてあるコメントは重要
50と132行目に "(stored in keys.conf)" とあるから keys.conf にも目を通す。
(5) https://help.gnome.org/admin/gdm/3.12/gdm.html [gnome.org]
GDM で XDMCP を設定する場合を想定してこれを挙げました。(タレコミのリンク先が XDMCP HOWTO だったので)
あたりを読めばいいんじゃないでしょうか。
昔からですな (スコア:0)
ドキュメントがお粗末なのは昔からだけど
最近のほうが目立つ気はするね
Googleさんに聞いて日付の新しいのを見つくろって
straceして触ってるファイル見て
ダメそうならソース眺めるかな
開発者のMLアーカイブあるとそれを丹念に見ていくと
重大なヒントがあることが多いけど
時間がかかるから余程必要にならないとやらない
このドキュメントだめだめ現象はもう絶対改善されないと思ってる。だれもやらないんだから、良くなりようがない
至上のドキュメント、それはソオス (スコア:0)
オープンソース界隈の人って、
「ホホホホ、ドキュメントがだめならソオスを読めばいいじゃない？」
って考えてるよね？
確かにマニュアルに書いていないオプションが見つかったりするけども。
そういえばtexのソースコードってドキュメントとごちゃごちゃに混ざっていて、Ｃ言語にするために一度変換するんだったっけ。
Re:至上のドキュメント、それはソオス (スコア:1)
マリーアントワネットの後を追ってほしいものです。
Re: (スコア:0)
オープンソース界隈の人間を斬首せよと申すか。
いや別に構わんけど。
アナザーマリー (スコア:1)
「ドキュメントが無いならあなたが書けばいいじゃない？」
OSSって本来そういうもんだけど、まあただの利用者にはしんどいよな。
# 自分の好きな分野、誰も書いてくれないからWikipediaにめっちゃ書いた。
Re: (スコア:0)
ああこれ。
で実際にやってみると「ドキュメント最新版に追いついてないだろクソボケ」と言われやる気をなくすと。
Re:アナザーマリー (スコア:1)
ドキュメントに限った話じゃない。クレクレ君は自分は指一本動かす気ないのに上から目線なのだ。
Re:アナザーマリー (スコア:2, すばらしい洞察)
使い方が分からないからドキュメントを探しているということは、まだ使っていないということなのに、ただで使わせてやるんだから感謝しろって一体どういう事なんだ。
Re:アナザーマリー (スコア:1)
そんなじゃ過疎りもしますわ
Re: (スコア:0)
オープンソース界隈の人って、
「ホホホホ、ドキュメントがだめならソオスを読めばいいじゃない？」
って考えてるよね？
だから一般にはいつまで経っても浸透しないんだよね。そのくせ、～が普及しないのはなぜか？ってあほな議論をする。
Re:至上のドキュメント、それはソオス (スコア:2, すばらしい洞察)
それもなんか違う。一般に浸透しているソフトだと「コレとコレを設定すればおk」みたいな簡易説明サイトがあっちこっちに出来る→本家のドキュメントは整理されない…
とゆーか、本家のドキュメントなんて誰もみないでその手の説明してくれるサイトばっか参照される
この辺の流れはFOSSに限らず、プロプラでもゲームソフトでもなんでもソー
Q&Aサイトでも本家のマニュアルじゃなく簡易説明サイトのリンクが貼られちゃったりするし…
Re: (スコア:0)
言われて見れば、プロプラのドキュメントも碌に読まないな。開発でも。
Re:至上のドキュメント、それはソオス (スコア:1)
簡単に動かせるようになるまで解説サイト、
動くようになったら公式のマニュアルしか読まないようにしてる。
なのでマニュアルが糞なOSSは使用しないようにしてる。
# RHEL も使用やめたいが難しい…。
[Q][W][E][R][T][Y]
Re: (スコア:0)
MSDNは結構読む。昔に比べればクオリティ落ちたけども。
Re:至上のドキュメント、それはソオス (スコア:1)
Re: (スコア:0)
ゲームソフトに関しては「攻略法を見て効率的にやりたい層」と「自分で手探りで攻略法を編み出して行きたい層」がいて
ゲーム会社もどちらにも対応できるように、ゲーム本体につける説明書は最低限にしてるだけだろう
前者に対しては攻略本という形でデータが供給されるし、最近はWikiとかもできるようになってきたけどさ
実用ソフトで「自分で手探りで使い方を編み出せ」とかあったら間違いなくゴミクズだけどな
Re:至上のドキュメント、それはソオス (スコア:1)
「オープンソース界隈」の人と「オープンソースの中の人」が別だから。
そういう議論をしてる人は、基本的に開発者ではない。
やれやれ・・・ (スコア:0)
基本がなってない [ansaikuropedia.org]
Re:タレコミの文章が残念で読む気にならなかったら、どうやって解決する? (スコア:2)
何のための編集者だよ
Re:複雑化して誰が分かるのかも謎になった (スコア:1)
> 大抵の設定ファイルはhomeに非表示であるからhomeだけコピペでいいじゃないですか。
そうなんですか？
当方、普段使いはWindowsで、Linux勉強中ですが、何をするにも/etc/配下のファイルをやたらと書き換える必要があるなー、という印象がすごく強いです。
というか、Linuxに限らずUnix系のOSでクソだなー、って思うのが
/var/
とか
/etc/
とか
/mnt/
とか、ぱっと見何のフォルダなのか意味がわからん所です。
むかーし、MS-DOSの時代に「ファイル名が8文字までとか、プギャー」とよく煽られたものですが、なんでファイル名に制限のないUnix系列のOSが一々省略したり、もって回った記述するのか、意味がわかりません。
普通に
/Programs/
とか
/Settings/
とか
initialize.daemon
とか、わかりやすい名前付ければいいのに……。
互換性云々が問題になるなら、せめてシンボリックリンクでも使って徐々にわかりやすい名前に移行とかする気ないんでしょうかねぇ……。
#気が付いたら愚痴になってしまった……。
Re:複雑化して誰が分かるのかも謎になった (スコア:1)
grubとかkernelとかdaemonの設定なら仰る通りですが。
sambaなんかディストロによってもバージョンによっても変わるし、まったくもう。
#やっぱり愚痴になりますね
Re:複雑化して誰が分かるのかも謎になった (スコア:1)
うーん、それを言ってしまったら主観になる、という結論にしかならないのでは？
何度も例に挙げてますが、略語を使わない、それだけでも変わるんじゃないかなー、と思います。
普段略語使ってるからって、略語じゃなくてフルスペルだとよくわからん、なんて人はいないと思いますし。
打つのがめんどくさいなら、シェルに補間機能でも追加すれば良いわけで。
そういう細々としたものを集積していく事が必要なのだと思うんですが、Unix系OSにはその気配すら見られないのでちょっとどうなんだそれ、って思ってるわけです。
期せずして貴方のコメントでオフトピから戻せそうですが、
> うっかり立ち上げたら終わらせ方が想像すらできん vi や emacs が
> いまだに愛用されている理由を考えてみよう。
こういう惰性的な部分が、今回のドキュメント不足に繋がってるんじゃないかなー、と思います。
わかってる人はわかってるので、そりゃあそういう人にとってはドキュメントは必要ないわけで。
で、そこで思考停止してしまったら、そりゃあもう本トピの様な問題提起がされるのは必然でしょう。
#:wq