Closed m-tmatma closed 5 years ago
berryzplus
commented
5 years ago あれ？なんで「appveyor の設定方法」って項目あるんでしたっけ？ 本質的によく分かってないだけなのかも知れんのですが、パッと見不思議に思いました。
英語にすると How to make appveyor setting. みたいなタイトルだと思います。
実際の内容は Discription about our appveyor settings. のような気がします。
じつは英語も日本語もあんまし得意じゃない・・・ :smile:
m-tmatma
commented
5 years ago しまった。toc が反映されないままマージしちゃった。
m-tmatma
commented
5 years ago 例えば、テレビの設定とか、パソコンの設定とかいう時と同様かと思います。
m-tmatma
commented
5 years ago @takke さん この PRでは別に問題ないですが、 PRを書き換える場合は事前に PR の作者に確認を取ってからにした方がいいです。 作者が PRを更新する作業を裏でやっていてまだ push してないだけなのかもしれないからです。 それでコンフリクトが発生したり、やり直しが発生したらやる前に確認してよ、という話になります。
m-tmatma
commented
5 years ago m-tmatma
commented
5 years ago @takke さん markdown の編集に上記の wiki のように visual studio code とプラグインを使えば toc の更新に関してファイルを保存するだけでやってくれるので楽です。 修正 PRをお願いできますか？
KageShiron
commented
5 years ago あれ、appveyor.mdの内容がStructure.mdに重複して入ってませんか？
m-tmatma
commented
5 years ago そうですね。修正します。
m-tmatma
commented
5 years ago あれ、appveyor.mdの内容がStructure.mdに重複して入ってませんか？
toc も更新しました。
takke
commented
5 years ago この PRでは別に問題ないですが、 PRを書き換える場合は事前に PR の作者に確認を取ってからにした方がいいです。 作者が PRを更新する作業を裏でやっていてまだ push してないだけなのかもしれないからです。 それでコンフリクトが発生したり、やり直しが発生したらやる前に確認してよ、という話になります。
そうですよね。失礼しました。 今回はちょっとした文言の修正だったのでレビューで手を煩わせてしまうより修正してしまったほうが早いかと思いましたが修正漏れもあったのでちゃんと手順踏んだ方がいいですね。気をつけます。
berryzplus
commented
5 years ago ←ついてけてない人。
@m-tmatma さん
例えば、テレビの設定とか、パソコンの設定とかいう時と同様かと思います。
「同様」の意味が分からんとです。 テレビは買ってきたものを改造せずに使うのが普通です。 パソコンは少し微妙ですが・・・「改造せずに使う」前提の取説が付いてます。 このリポジトリのドキュメントは「改造して使ってもらうため」に付けてると思います。
改造して使う人に向けたドキュメントなので、 設定手順や設定内容は説明できても どうしたら使う人の思い通りに動くかは書けない気がするんです。
m-tmatma
commented
5 years ago 「同様」の意味が分からんとです。 テレビは買ってきたものを改造せずに使うのが普通です。 パソコンは少し微妙ですが・・・「改造せずに使う」前提の取説が付いてます。 このリポジトリのドキュメントは「改造して使ってもらうため」に付けてると思います。
内容に関して、「同様」といったわけではないです。
〇〇の設定 という場合、〇〇 の部分が設定対象ということです。
「appveyor の設定」は appveyor という対象に対する設定ということです。
パソコンとテレビの例でも設定対象です。
takke
commented
5 years ago 例えば、テレビの設定とか、パソコンの設定とかいう時と同様かと思います。
私は「同様」と言われて腑に落ちた派です。 うーん、日本語の問題とは思うんですが、、
改造して使う人に向けたドキュメントなので、 設定手順や設定内容は説明できても どうしたら使う人の思い通りに動くかは書けない気がするんです。
ということは、「appveyor の設定方法」ではなく「appveyor の設定手順」または「appveyor の設定内容」であればいい感じですか？
ds14050
commented
5 years ago 自分は傍観者なので以下はただの感想・雑談です。
理由は「README.md が長くなって見にくいので」ということでした。
Web に置いてあるドキュメント一般についてですが、同じ内容でページ分割版と単一HTML版の２種類が用意されているのを見たことがあると思います。自分は迷わず単一HTML版を選ぶ人間です。
単一ページ版の完全勝利でページ分割版を求める人がエイリアンに見えます。
そういうわけなので「README.md はリポジトリのトップページに内容が表示されるからサイズを制限したい」という理由があるのかなと期待したりしました。
追記> 他人の口を借りてしゃべってはダメですね。外していました。<追記
読者の想定にブレがあるということが言いたいのかなと思いました。
README.md の前半はリポジトリの訪問者に対してリポジトリの位置づけや内容を紹介して意見を募集しています。
対して「appveyor の設定方法」はリポジトリの楽屋裏の解説になっています。訪問者は楽屋裏を解説されて「え、自分が AppVeyor を設定して動かすの？」という疑問を持つと思います。
訪問者向けの文章と内輪向けの文章が混じっているんですね。
m-tmatma
commented
5 years ago 一般ユーザー向けの情報と開発者向けの両方を説明するにあたって もともと同じ README に全部書いていて、それでは見通しが悪くなるので分割しました。
README はトップページの役割をするので、開発者向けの情報へのリンクがあるのは自然なことと思います。
m-tmatma
commented
5 years ago Web に置いてあるドキュメント一般についてですが、同じ内容でページ分割版と単一HTML版の２種類が用意されているのを見たことがあると思います。自分は迷わず単一HTML版を選ぶ人間です。
両方用意されているということは、両者にメリット、デメリットがあり、どちらか一方に 決められないから、両方用意しているのだと思います。
トイレットペーパーはシングル派？ ダブル派？ というな話と同様なのかもしれません。何を重視するのかによります。
web サイトで両方用意している場合は、なにかマスターとなるデータがあってそれから自動生成して、 両方のバージョンを作成していると思われるのでそのようなことができますが、 markdown の場合は、そのようなことはできません。どちらかに決めて実装する必要があります。
berryzplus
commented
5 years ago @m_tmatma さん
内容に関して、「同様」といったわけではないです。
〇〇の設定 という場合、〇〇 の部分が設定対象ということです。
「appveyor の設定」は appveyor という対象に対する設定ということです。 パソコンとテレビの例でも設定対象です。
「設定」が同様なのは分かりました。 設定「方法」って何でしたっけ？のつもりです。
@takke さん
改造して使う人に向けたドキュメントなので、 設定手順や設定内容は説明できても どうしたら使う人の思い通りに動くかは書けない気がするんです。
ということは、「appveyor の設定方法」ではなく「appveyor の設定手順」または「appveyor の設定内容」であればいい感じですか？
そんな感じです。
appveyorの設定について読む人は「your settings」を作るために読むはずだと思います。 こちらで語れるのはあくまで「our settings」であって、 「your settings」のことは「知らんよ」だと思うんです。
「How to make settings」なニュアンスだと「設定の仕方を教えてやる！」な感じがして 「あれ？そこまで突き詰めて調査したんだっけ？」な違和感を持った次第なのです。
README.md を複数ファイルに分割する
9