Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

READMEを書こう

118 views

Published on

「新しいLinuxの教科書」を読む会 オンライン #2 で行ったREADMEについてのプレゼン資料です。
https://linuxbook.connpass.com/event/178366/

Published in: Technology
  • Be the first to comment

  • Be the first to like this

READMEを書こう

  1. 1. READMEを書こう 2020年06月20日
  2. 2. 自己紹介 名前: 三宅 英明 Twitter: @mollifier 神戸のプログラマ
  3. 3. シェルスクリプト
  4. 4. シェルスクリプト 「新しいLinuxの教科書」を読むと、かっこいいシ ェルスクリプトが作れるようになります
  5. 5. シェルスクリプト みなさんにもぜひ挑戦してほしい 出来上がったらみんなに公開してほしい
  6. 6. シェルスクリプト 公開
  7. 7. シェルスクリプト 公開するときにつきものなのがREADMEファイ ル
  8. 8. READMEとは
  9. 9. READMEとは アプリケーションやコマンドラインツールにだいた い付いているやつです
  10. 10. READMEとは
  11. 11. READMEとは
  12. 12. READMEとは アプリケーションの使い方や注意点などを書い た文章
  13. 13. READMEとは 何か自分でツールを作ったとします
  14. 14. READMEとは それだけではどうやって使えばよいか分からない
  15. 15. READMEとは 公開しても誰も使ってくれない
  16. 16. READMEとは というか、自分でも使い方を忘れてよく分からな くなる
  17. 17. READMEとは READMEがちゃんとしていたら本格的な感じが 出てくる
  18. 18. READMEとは でもいざ書こうとしてみると、意外と難しい
  19. 19. READMEとは というわけで、今日はREADMEの書き方につい てお話します
  20. 20. READMEの目的
  21. 21. READMEの目的 何のためにREADMEを書くのか
  22. 22. READMEの目的 目的1 そのアプリケーションを初めてみた人が、 READMEを読んでそれを使うかどうかを判断す る
  23. 23. READMEの目的 目的2 アプリケーションを使い始めた人が、README を読んで使い方を知る
  24. 24. READMEの目的 まだインストールしていない人か、使い始めた人 向けに書く
  25. 25. READMEに何を書くか
  26. 26. READMEに何を書くか まだインストールしていない人か、使い始めた人 向けに書く
  27. 27. READMEに何を書くか そう考えると、だいたい書くことは決まってくる
  28. 28. READMEに何を書くか 典型的な例 Name Description
  29. 29. READMEに何を書くか 典型的な例 Install Usage Option Configuration
  30. 30. READMEに何を書くか Name 名前
  31. 31. READMEに何を書くか Name もちろん必要 かっこいい名前にしよう
  32. 32. READMEに何を書くか Description 1、2行の簡単な説明
  33. 33. READMEに何を書くか Description それが何なのか説明がないと意味がわからない READMEの最初の方に書く
  34. 34. READMEに何を書くか 説明が難しいなら、画像が有効
  35. 35. READMEに何を書くか DEMOとして書いてあることがある 使ってる様子の紹介、スクリーンショットなど こういうのを足すのもあり
  36. 36. READMEに何を書くか Install インストール、初期設定の方法
  37. 37. READMEに何を書くか Install 最初の手順が分からないと使えない
  38. 38. READMEに何を書くか Install 1行のコマンドでインストールできるのが理想
  39. 39. READMEに何を書くか 1行で無理なら必要なコマンドを全部書く $ git clone https://github.com/tool.git ~/tool $ cd ~/tool $ ./setup.sh
  40. 40. READMEに何を書くか 単純にコピペで実行できるように READMEを読む人は何も分かってないことに気 をつけよう
  41. 41. READMEに何を書くか Usage 使用方法、起動方法
  42. 42. READMEに何を書くか Usage 一番大事 「こうやって実行したら、こうなる」という形で書く
  43. 43. READMEに何を書くか 例 $ bookmark add 現在のディレクトリをブックマークに追加します
  44. 44. READMEに何を書くか Usage 説明が難しかったら、例を書くのも良い
  45. 45. READMEに何を書くか # ~/workをブックマークに追加する $ bookmark add work ~/work $ cd ~/tmp # workという名前で~/workに移動できる $ bookmark cd work
  46. 46. READMEに何を書くか Option オプションの説明
  47. 47. READMEに何を書くか Option オプションがあるなら書く (当たり前ですが)書かないと分からない
  48. 48. READMEに何を書くか Option これも、説明が難しかったら例を書くのも有効
  49. 49. READMEに何を書くか Configuration 設定方法
  50. 50. READMEに何を書くか Configuration 環境変数、設定ファイルなどで設定を変更できる なら、その説明を書く
  51. 51. READMEに何を書くか 典型的な例 Description (名前) Description (簡単な説明)
  52. 52. READMEに何を書くか 典型的な例 Install (インストール) Usage (使用方法) Option (オプション) Configuration (設定方法)
  53. 53. READMEに何を書くか 内部の詳細とかは書かなくてもよい
  54. 54. READMEに何を書くか ユーザーはそんなこと気にしない そこまで読んでくれない
  55. 55. READMEに何を書くか 外から見た動作を書けばOK
  56. 56. READMEを書く時のコツ
  57. 57. READMEを書く時のコツ 自分でコマンドラインツールとかを作ってるとき
  58. 58. READMEを書く時のコツ だいたい、実装してるときが盛り上がりのピーク
  59. 59. READMEを書く時のコツ 完成すると達成感がある
  60. 60. READMEを書く時のコツ そのあとREADMEを書こうとしても、だいたいや る気が出ない 地味すぎる
  61. 61. READMEを書く時のコツ READMEは本体を実装する前に書くのがよい
  62. 62. READMEを書く時のコツ 実装する前に、このツールで何をしたいのかを決 めて、それを書く
  63. 63. READMEを書く時のコツ 先に外から見た動作をREADMEに書いて、そう なるように内部を実装する ちょっとした仕様書としても使える
  64. 64. READMEを書く時のコツ 実装する前なので、最初に使うユーザーと同じ 気持ちで書ける
  65. 65. READMEを書く時のコツ 実装していくうちに詳しくなって、ユーザーの気 持ちを忘れてしまう
  66. 66. READMEを書く時のコツ 「こういうふうに作りました」ではなく「こういうふ うになっていてほしい」「こういう使い方をした い」というユーザー目線で仕様を決めてそれを 書く
  67. 67. READMEを書く時のコツ そうやって仕様を決めると使いやすくなるはず
  68. 68. READMEを書く時のコツ というわけで、先に書くのをおすすめします
  69. 69. まとめ
  70. 70. まとめ READMEは大事
  71. 71. まとめ めんどくさいので雑になりがち
  72. 72. まとめ 初めのうちは他の人が作ったツールとかを参考 にするのがよい
  73. 73. まとめ 慣れてくると大体パターンが決まってくる
  74. 74. まとめ なので、世の中にあるいろんなアプリケーション とかツールとかを使ってみるのが大事
  75. 75. まとめ 盛り上がってきたらぜひ自分でもぜひコマンドラ インツールを作ってみてください
  76. 76. まとめ そのときは、この発表とか「新しいLinuxの教科 書」とかも参考になると思います
  77. 77. まとめ ありがとうございました

×