sakura
sakura copied to clipboard
sakura-editor
README.mdに記載する内容を再考してはいかがでしょうか？
記述が古いことよりも、記述位置が不適切なことのほうが気になってそちらを直したくなってしまうので、仕切り直したほうが良さそうに思いました。
発覚した問題点は、具体的に報告しましょ。
発覚した問題点
- README.md の記述内容が、ぶっちゃけおかしい。
- TOC（＝Table Of Contents ≒ 目次）の位置がおかしい。
- Hot Topic が 事実上 stale。
- Web Site の heading がたぶん無駄。
- 開発参加ポリシー の 記載がたぶん無駄。
- 「サクラエディタ？何それ、おいしいの？」に関する説明がない。
- サクラエディタ「そのもの」の使い方に関して一切説明がない。
- Build Requirements がここにある理由が謎。
- How to build がここに必要な理由が謎。
- How to install がここになくて良い理由が謎。buildがあるなら用意するのが普通。
- How to use がここになくて良い理由が謎。buildがなくても用意するのが普通。
- how to build より下に書いてある項目が、全項目意味不明。 👈思考停止。
既知の問題として以下のものがあります。
- #740 トップディレクトリのファイルを整理する
Originally posted by @berryzplus in https://github.com/sakura-editor/sakura/pull/1437#issuecomment-716117488
- how to build より下に書いてある項目が、全項目意味不明。 👈思考停止。
変更履歴は changelog 見てね！というのはREADMEにあっていいと思います。
お疲れ様です。
まったく同じ内容のissueを立てようと #1437 の変更内容をもとに自分のイメージに合わせて作成したものを用意していました。 参考になるかはわからないですが置いておきます。 https://github.com/sakura-editor/sakura/compare/master...kazasaku:feature/fix_project_documents
他プロジェクトを参考にしてみるアプローチ
- SAKURA Editor https://github.com/sakura-editor/sakura
- vsCode https://github.com/Microsoft/vscode
- vim https://github.com/vim/vim
- notepad++ https://github.com/notepad-plus-plus/notepad-plus-plus
アプローチしてみて思ったこと
- TOCあるのは、サクラエディタだけじゃんね・・・。
- What's this? に相当する説明がないの、サクラエディタだけじゃんね・・・。
- 他のプロジェクトに比べると、サクラエディタはビルドに関する説明がやたらと詳しい気がしました。
- how to build より下に書いてある項目が、全項目意味不明。 👈思考停止。
変更履歴は changelog 見てね！というのはREADMEにあっていいと思います。
それは確かにｗ
Build Requirements がここにある理由が謎。
Build Requirements に関しては build.md ファイルに移した方が README.md ファイルはすっきりしそうですね。
How to build がここに必要な理由が謎。
今は下記のように書かれています。
How to build
- 7Zip のインストールして 7z.exe へのパスを通します。
- Visual Studio Community 2017 で
sakura.slnを開いてビルドします。詳細情報
詳しくは こちら を参照
単に build.md ファイルへのリンクにするだけでも良いかもしれないですね。
VSCode だと ビルド方法とかについては README.md から wiki の解説ページへリンクを貼っています。
頻繁に記載を更新するものは wiki のページで済ませるのが良いかもしれないですね。ただ wiki は見ないという人もいると思いますが…。
How to install がここになくて良い理由が謎。buildがあるなら用意するのが普通。
How to install に具体的に何を記載するべきかについて案はありますか？
インストーラーを作成する為に必要な環境構築の解説でしょうか？
How to use がここになくて良い理由が謎。buildがなくても用意するのが普通。
How to use ってサクラエディタの使い方の事ですか？
https://sakura-editor.github.io/help/
に書かれているのでそれを読めばよいと思いますが、そこへのリンクが欲しいという事でしょうか？
how to build より下に書いてある項目が、全項目意味不明。 👈思考停止。
CI関連の説明のリンクを個別に README.md に載せる必要があるかというと無いかもしれません。
個人的には wiki に説明が書かれていればそこを見ればよいので、README.md にはリンクは不要だと思います。が、人によっては心理的障壁で wiki が見れないので README.md に全て記載してほしいと強く主張するかもしれません。自分がそれに対して出来る事はテーブルに両肘を付いてから両掌で顔を覆い項垂れて静かに息を吐きだすくらいです。
How to install がここになくて良い理由が謎。buildがあるなら用意するのが普通。
How to install に具体的に何を記載するべきかについて案はありますか？
インストールしなくても使えますよ、という情報ではないかと思います。
How to use がここになくて良い理由が謎。buildがなくても用意するのが普通。
How to use ってサクラエディタの使い方の事ですか？
おそらく、使い道の紹介でしょうね。 ここは、何に使えるツールなのかを表明しておく場所だと思います。 あと、細かいことはここを見てね、はあったほうがよいと思いました。
が、人によっては心理的障壁で wiki が見れないので README.md に全て記載してほしいと強く主張するかもしれません。
wikiが見れない人は単純に問題外ですので、配慮不要と考えられます。
ドキュメントの履歴を残せるように可能な限りREADME.mdに情報を詰め込みたいという書き込みを見たように思います。
第三者の承認が必要なREADME.mdに試行錯誤中の情報を含めるべきではないように思いますが、どうしてもそうしたいなら仕方ないようにも思います。
現時点で分かっている情報を書く ↓ あとの時代で「正しくない」と判明する ↓ 修正PRは「誤りを正す」とせざるを得ない ↓ あとの時代に「誤りだ」と言われたくないから、レビューが無駄に慎重になる