00:06
8月8日、月曜日ですね。 地獄は昨日もありました。
最近は、夏は毎年そうなんですけど、 汗をかいたからシャワーを浴びるんですけど、
シャワーを浴びたせいで大量に汗をかくという、 自己矛盾と毎年戦ってます。
はい、おはようございます。 姫美のkeethことくわはらです。
では本日も朝活を始めていきたいなと思います。
今日はタイトルがありますけど、「Art of README」っていう、
このタイトルというか、これ自体がリポジトリなんですね、そもそも。
ハッケグリさんっていう、読み方がちょっと分からないですけど、
っていう方が書かれている、 アートオブリードミーっていうリポジトリがあって、
これ本当に、ただ単にアートオブリードミーっていう、 リードミーのMDだけがガンと置いてあるリポジトリですね。
それに各それぞれの言語に翻訳された、 MDがそれぞれ置かれてますって感じですね。
翻訳されている言語としては中国語、日本語、 ブラジル語、ポルトガル語かな?
あとスペイン語、ドイツ語、あとフランス語ですね。
なのでだいたい6大言語もいくつか入ってるっていうような感じですね。
っていうところです。
このREADMEそのものをどうやってアートするとか デザインするかみたいなところの話だと思うので、
これはエンジニアとして結構大事な話になってくれると思って、 読んでいこうかなと思っています。
では早速、今回は嬉しいことに日本語の翻訳もあるので、 そこをちょっと読ませさせていただきたいなと思ってます。
では早速入っていきたいと思いますけども、
しちゅうゆうせんさんですね。 おはようございます。ご参加いただきありがとうございます。
ねぶさんと、やみことあっておかないすげーやずきさんですかね。 ご参加いただきありがとうございます。
タイトルあるとおりですけども、READMEのアートのリポジトリ型の それを今から読んでいこうかなと思っています。
READMEの語源はそもそも何でしょうかと。
この命名は少なくとも1970年代のPDP-10というものがあって、 これもリンクを貼れてますね。
PDP-10まで遡りますが、もしかしたらパンチカードの束の上に READMEと書かれた紙のメモを置いて、
使い方を説明していた時代まで遡るかもしれませんと。
昔はそんなことやってたんですね。 パンチカードの束の上にこれ見ろってREADMEを書かれていた紙のメモを置いてあったんですね。
そこに一応説明文が書いてあったらしい。 そんな時代があったんですね。
読者の方からREADMEはルイス・キャロルの 不思議の国のアリスに登場する
ドリンクミーと書かれた飲み癖やイートミーと書かれたケーキを 意識しているのだというふうな指摘もいただきましたと。
一応それに関する参考リンクも一応リンクとして貼っています。
不思議の国のアリスは確かにそういう書き方をしますもんね。
その中の一つに読めというのでREADMEが出たのかというのもあるかもしれません。
READMEというのは歴史的にすべて大文字で表記されてきました。
03:00
すべて大文字を使用することで視覚的なインパクトがあることに加えて、
UNIXシステムというのは小文字の前に大文字を相当するので、
ディレクトリ内の他のコンテンツよりREADMEを優先させることもできますと。
なるほどね。そういう指摘もあったところですね。
その意図は明確で、この情報はユーザーが先に進む前に読むべき重要な情報ですよということを意味しています。
ではこの現代においてこの重要な情報とは何なのかというのを一緒に探ってみましょうというところからスタートですね。
確かにね、言われてみればそもそもREADMEってなんぞやというところですよね。
その中で確かに重要なものって何だろうというのは、現代においてというのは結構大事かもですね。
では行きます。製作者向けかつユーザー向けというところですね。
本記事はREADMEについての記事ですと。
READMEが何をするのか、なぜ絶対に必要なのか、そしてどのようにうまく作るのかについて書かれています。
本記事はモジュールの製作者向けに書かれたものです。
モジュールの製作者というのは仕事は長く使えるものを作ることです。
これはたとえ製作者が自分の作品を共有するつもりがないとしても内波的な動機でしょうと。
共有するつもりなくても未来の自分に対して書いておくというのは絶対重要だと思うので、書いて損はないと思いますけど。
6ヶ月も経つとドキュメントのないモジュールというのは製作者にも見慣れないものに見えてきます。
書いてあるじゃん。
本記事はまたモジュールのユーザー向けにも書かれています。
全てのモジュール製作者というのはモジュールのユーザーでもあります。
ノードは非常に健全な相互依存性を持っており、依存関係ツリーの最下部には1つのモジュールもありませんと。
ここではノードに焦点を当てていますが、
フィッシャーはその教訓というのは他のプログラミング言語のエコシステムにも応用できると考えています。
今回のノードというのはノードJSのことですね。
では次のセクションですけど、
抑制器混合のたくさんのモジュールというところです。
ノードのエコシステムというのはモジュールによって支えられています。
NPMというのはそれを実現するための魔法ですと。
ノードJSの開発者というのは彼らのプロジェクトに含まれる何十ものモジュールを短い間に評価します。
NPMインストールとさえかければ日々の業務に有益なモジュールを引っ張ってくれるというのは確かにすごいことにはなりますと。
確かに本当にすごいことだと思いますね。
あんだけの依存関係だったり複雑だったりワーってなっているものをまとめてドワッとインストールしてくれるというのは確かにすごいことではあるんですよね本当に。
結果ノードモジュールズというディレクトリ内は凄まじいことになっていますけど。
アクセスしやすいエコシステムではよくあることですけど、モジュールの品質にはばらつきがあります。
NPMというのはモジュールをすべて綺麗に梱包して広く届けるために最善を尽くしています。
しかし発見できるツールは多種多様でピカピカで新しいものもあれば壊れて錆びついたものもあり、またその中間のものもあります。
中には何をするものか分からないものまであります。
モジュールで言えば不正確な名前や役に立たない名前。
フッチモジュールが何を意味するか分かりますか?
06:00
フッチモジュールって確かにあるんですね。
NPMサーチで調べたら多分出てくると思うんですけど。
NPMサーチで調べると普通にホゲっていうモジュールもありますし、アーっていうのもありますし、本当にクソくだらないものがたくさんあるので、そういうものを一回削除してほしいんですけどね。
雑音が増えますのでね。戻ります。
ドキュメントがないもの、テストがないもの、ソースコードコメントがないもの、理解しがたい関数名を持つもの、たくさんのよく分からないモジュールがあるというところですね。
多くのケースではアクティブなメンテナーはいません。
もしモジュールの質問に答えたり、モジュールの機能を説明したりできる人がいなければ、ドキュメントがないことと相まって、モジュールはエイリアンのアーティファクトとなり、使い物にならず、理解もできないものになるでしょうと。
ドキュメントがあるモジュールの場合は、その品質はどれくらいのものでしょうかと。
16信数で数値を相当するという1行だけの説明かもしれません。あるいはサンプルコードのスニペットだけかもしれません。
どちらも何もないケースと比べれば進歩と言えますが、現代のモジュールユーザーに実際にどのように動作するのかを理解するために、ソースコードを掘り下げるという最悪のシナリオをもたらすこともあります。
作れたドキュメントを書くことは、あなたのモジュールを十分に抽象化する説明を行うことで、ユーザーをソースコードから遠ざけることになるのです。
それは良い話ですね。
ノードというのは広大なエコシステムで、一つのことに特化し、互いに独立した非常にたくさんのモジュールで構成されています。
一応例外というのもありますけれども、その例外は一応リンクを貼られていまして、その例外とはローダッシュのことですね。
あれは確かにそれ自体が一つのものというよりも、あれは分解されたものの集合体ではありますから、確かに例外ではあります。
例外はありますが、こうした小さな領地はあっても、一点に特化した市民たちがその数の多さからノード王国を真に支配しています。
このような状況では当然の期決ですが、欲しいものを正確に実現する質の高いモジュールを見つけるのは大変でしょう。
これで問題ありません。本当に。これ自体は別に問題ない。
参入のハードルの低さと検索性の低さという問題は、一部の特権階級しか参加できない文化の問題よりも非常に良いことだというふうに捉えています。
加えて検索性の低さというのは結果的に対処しやすいものにもなると。
まあまあ、そりゃ言われればそうですね。
とはいえ検索性低いというのは、なると欲しいものにたどり着かないという時間を奪われるのであんまりよろしくないと思いますけどね。
続きます。
前線の道はreadme.mdに通ずと。
ノードコミュニティというのは様々な方法で検索性の低さに対応してきました。
ベテランのノード開発者が結束して良質なモジュールのCurationリストというのを作成しました。
Curationリストというのは、これもGitHubのリポジトリが貼られてるんですけど、AwesomeNodeJSというリポジトリがありますね。
これが一応Curationのリストだそうです。
僕見たことなかったんですけどね。
09:00
シンドロソーラスさんという方のAwesomeNodeJSというものがありますね。
めちゃめちゃ巨大だな。
なるほど。
確かに本当にリストって感じがします。
もし興味ある方は見てみてください。
Curationリストを作成してます。
開発者たちは長年にわたって何百ものモジュールを調査し、それぞれのカテゴリーで最高のモジュールをノードの初心者のために公開しています。
これはまた信頼できるコミュニティメンバーによって有用だとみなされた新しいモジュールのRSSフィードやメーリングリストの形式を取ることもあるかもしれません。
ソーシャルグラフというアイディアはNodeModules.comの作成に拍車をかけました。
このNPM検索代替ツールというのは、あなたのGitHubのソーシャルグラフを使用して、あなたの友人が好きなモジュールや作成したモジュールを見つけることができるのです。
NodeModules.comというのがあったんですね。
長年後、ノードで仕事をしているんですけど、ノードというかJavaScriptで仕事をしているんですけど、全然このサイトは知りませんでした。
ただ、今アクセスしたら、ノットファウンドが返ってきますね。
これ動いていないんじゃないか。
まあいいや、戻りましょう。
もちろんNPMその名付けの検索機能というのも一応あります。
検索機能というのはNPM本体の公式サイトですね。
というのもあります。
安全で一般的な選択肢であり、新しい会社のためにいつも開かれています。
どのようなアプローチをとろうとも、モジュールユーザーがnpmjs.orgやgithub.comなどで検索しても、
ユーザーは最終的にはあなたのReadMeと正面から向き合うことになるのですと。
ユーザーは必然的にここにたどり着くわけですから、彼らの第一印象を最大限に良くするために何ができるでしょうかというのが次のステップですね。
一つ目ですけど、プロフェッショナルなモジュール探索というところですね。
皆さんにそこから小さなカテゴライズされています。
まずはReadMeのワンストップショットというやつですね。
ReadMeというのはモジュールのユーザーにとって最初のそしておそらく唯一のあなたのモジュールに関する情報ですと。
ユーザーは自分のニーズを満たすモジュールを求めているので、
あなたは自身のモジュールがどのようなニーズを満たし、どのように効果的にニーズを満たすかを正確に説明する必要があります。
あなたの仕事は文脈を含めてモジュールが何であるかを伝える、実際にどのように見えるかを見せる、
使い方を紹介する、その他の関連する内容を伝えるというところですね。
これがあなたの仕事になりますと。
自分の作品が粗悪なモジュールの海の中で輝く宝石であることを証明するのはモジュール作成者次第になります。
多くの開発者の目というのは何よりも先にReadMeに向くので、
ReadMeの秘密があなたの作品の評価基準になるのですと。
言われてみればでも実際そうかもですね。
結局欲しいモジュールをバーっと検索してざっと眺めますけど、
だいたいReadMeを見て、そのReadMeに書かれているソースコードをパッと動かしてみて、
これで良さそうになったら導入するというのは多いので。
だけどReadMeがなかったら僕も見ないことが多いですね。
12:02
わざわざソースコードを見るまで時間はないですからね。
続いて簡潔さですね。
ReadMeがないのは大きな危険信号ですが、ReadMeの長さが秘密の高さを示すというわけでもありません。
理想的なReadMeはこれ以上短くならないほどに短いものです。
詳細のドキュメントは別のページにして、
詳細のドキュメントは別のページにして、ReadMeそのものは簡潔にしましょう。
極力ならTable of Contentsに近いぐらいでもいいかもしれないですね。
ただまあちゃんと説明するものはしっかり説明しましょうと思いますけど。
続いて過去に学ぶというところです。
歴史をまだ学ぶ者は同じ過ちを繰り返すと言われます。
学ぶ者がドキュメントを書くようになってからかなりの年月が経ちました。
ノードが登場する前に人々が何をしているのかというのを少し振り返ってみる価値はあるでしょう。
Perlは否定されることもありますが、ある意味ではノードの精神的な祖父母にあたります。
どちらも高水準のスクリプト言語で、多くのユニックスイリアムを採用し、
インターネットの発展を牽引し、モジュールの広範なエコシステムを備えることを特徴としています。
PerlコミュニティのMonksたちは、
perlmonks.orgというリンクでした。
質の高いReadMeを書くことにかけては、実に多くの経験を積んでいることで知られています。
質の高いReadMeというところにもリンクが貼られていて、
これはちょっと僕の知らないサイトなので、ここはちょっと後ほど見てみてください。
CPANというのは、質の高い水準のドキュメントを書いたコミュニティについて
モッドを学ぶための素晴らしいリソースになります。
先ほどのReadMeのリンクですかね。
search.cpan.orgというところのサイトなので、
ここが色々高い質の品質水準のドキュメントを書くコミュニティの素晴らしいリソースだと言っていますので、
見てみてもいいかもしれないですね。
続いて、ReadMeがなければ抽象化できないというところですね。
ReadMeがなければ、ユーザーはモジュールを理解するためにコードを掘り下げる必要があります。
この問題に関しては、パール・モンクスは知恵を共有してくれています。
Ken Williamsという方が書かれているものの引用になりますね。
ユーザーがコードを見ることなくあなたのモジュールを使用できていれば、あなたのドキュメントは完璧だということです。
これは非常に重要です。
ドキュメントが完璧であれば、文書化されたインターフェース部分と内部実装を分離することが可能になります。
これはインターフェースが同じである限り、モジュール内部を自由に変更できることを意味するので、とても良いことです。
モジュールが何をするのかを定義するのは、コードではなくドキュメントであることを覚えておいてくださいというところでした。
もう本当に素晴らしい言葉ですね、これは。
その通りって感じがしました。
僕も何回いくつかNPMにモジュールアップしているので、この辺はやっぱり意識したことがあるので、その通りだなって感じます。
15:01
続いて重要な要素ですね。
ReadMeがあれば、モジュールユーザーはそれを読んで自身のニーズに合致しているかどうかというのを確かめなければなりません。
これは本質的には開発者の脳内で解かれる一連のパターンマッチング問題となり、一歩ずつモジュールの詳細について深く掘り下げていきます。
例えば、2Dの衝突検出モジュールというのを探していたとしましょう。
この場合は、colit2dabbabbみたいなものに対応するとしましょうと。
一応、そういう名前のちゃんとリポジトリが本当にありますね。
colit-2d-abb-abbっていう名前のライブラリーですね。
ギャグかと思ったら本当にリンクがありました。
私はこのモジュールを上から下まで調べましたと。
1、まず名前です。
自名の名前がベストになります。
colit-2d-abb-abbは期待できそうですが、これは私がAABBが何かを知っていることを前提としています。
もし名前があまりにも漠然としていたり無関係に思えたら他のモジュールに移るかもしれません。
2Dっていうワードが入っているから2D系のコリトであるから衝突なんだろうけど、
AABBって何?
僕とあったら私は確かに離れちゃうかもしれないですね。
続いて、ワンライナーですね。
モジュールを説明するワンライナーを持っていると、
モジュールが何をするのかを少しだけ詳しく知りたいときに便利です。
一応、この今回のcolit-2d-abbってやつは、
determine the weather moving axis aligned bounding box
それがAABBのリラックスですね。
axis aligned bounding boxの頭文字を取ってAABBだと。
で、colit with other ABBsっていうところですね。
このワンライナーの一行が入っていると。
確かに。
これあると少し分かりやすいんですね。
素晴らしいAABBとは何かというと、
モジュールが何かをするかを定義しています。
ではどのくらい私のコードにうまく組み込めるでしょうかというのが次のところですね。
続いて使い方ですね。
いわゆるユーズエッジってやつですね。
APIドキュメントを掘り下げ始めるよりも、
モジュールが実際にどのように見えるかを確認するのが良いアイディアです。
サンプルのJSが求めているスタイルや解決したい問題でマッチしているかどうかを判断できるからです。
プロミスやコールバックやES6といったものに対して、
多くの人が異なる意見を持っていることでしょう。
もし要求を満たしてくれるなら私はさらに詳細に進むことができます。
続いてAPIですね。
モジュールの名前だったり説明だったり、
そして使い方すべてが魅力的に思えます。
ここまでで私にとってはこのモジュールを使う可能性が非常に高いです。
APIをざっと見て私が必要とすることを正確に行い、
私のコードベースに正確に組み入れることが可能であることを確認する必要があります。
APIのセクションというのは、そのモジュールのオブジェクトと関数、
シグネチャー、戻り値の型、コールバック、イベントなどを詳しく説明する必要があります。
型が明らかでない場合はそれも含めるべきです。
注意書きも明確にすべきでしょうというふうに書いてありますね。
続いてインストール方法ですね。
18:02
ここまで読んだらこのモジュールを使ってみると気になります。
もし標準的でないインストール方法があればここに書くべきですが、
通常のnpmインストールであったとしてもそれについての言及は欲しいところです。
npmjs.orgへのリンクとインストールコマンドを書いてあげることで、
ノードの新しいユーザーはノードモジュールがどのように動作するのかを理解することができます。
あとはライセンスですね。
ほとんどのモジュールはこれを一番下に置いていますが、
実はもっと上にあった方がいいかもしれません。
あなたの仕事に不適切なライセンスを持つモジュールはなるべく早く排除したいでしょう。
私は一般にMITとかBSDだったりX11だったりISC風のライセンスにこだわります。
もしパーミッシブライセンスでないライセンスならば、
混乱を避けるために一番上に貼り付けておいてくださいということですね。
一応今はGitHubがその辺うまいこと表現するようになってくれたので、
基本的にドキュメントを置いておけばトップページのバーンといきなり目に映るところに置いてますし、
右のカラムにも表示されたりするので、
ここは意識しなくてもとりあえずライセンスファイルを置くだけで全然いいのかなと思ったりしてますね。
ReadMeの一番下に書くべきかというか、
それはあれですけどもリポジトリアクセスしている時点で見えるところに置いてあるから、
そこは意識しなくてもという気はしました。
続いてあと7分ですね。
Cognitive Funnelingというものですね。
なんだCognitive Funnelingはちょっと僕が初めて聞いたことかもしれないです。
上記の順序というのは何もランダムに選んだわけではありません。
以上さっきのやつですね。
もう一回名前を見ると1.2.3.4.5.6個あって、
上から順にいくと名前、ワンライナー、使い方、API、インストール方法、ライセンスですね。
この順番ですけども、これらは何もランダムに選んだわけではありません。
モジュールのユーザーというのはたくさんのモジュールを使用し、
そして多くのモジュールを調べる必要があります。
この多くのモジュールを見ていると予測可能なパターンに対して精神的な安定感を感じ始めます。
またどのような情報が欲しいのか、どのような危険信号があればモジュールは不適合だと素早く判断できるのか、
自分なりのヒューリスティックを構築し始めるのです。
したがってReadMeには次のようなものがあることが望ましいと言えます。
大きく2つですね。
1つ目は予測可能なフォーマットであること。
2つ目は特定の重要な要素が存在することです。
必ずしも常規のフォーマットを使う必要はありませんが、
ユーザーの貴重な認知サイクルの無駄を省くために一貫性を保たせるようにしましょう。
ここで紹介する順序というのがCognitive Funnelingと呼ばれ、
ロートを直立したイメージで最も広い端には最も一般的な情報が含まれていますと。
この辺ちょっと日本語訳がやわらかくて曖昧なのでここは英文を読みたくなりました。
ロートの奥に進むほどより具体的になり、
あなたの作品に興味を持ちその奥に到達した読書だけに適切な詳細があります。
最後に一番下には作品のより深い文脈ですね。
背景だったりクレジットだったり参考文献ですね。
21:01
に興味を持った人たちだけのためにそうした詳細を表示することができます。
今回またパールモンクスがこのテーマについて知恵を共有してくれています。
そこを引用読んでいきます。
パールモジュールのドキュメントは一般的にあまり詳細でないものからより詳細なものまであります。
Synopsysセクションには最小限の使用例、
おそらく1行程度のコードで例外やほとんどユーザーが必要としないものは省略してくださいという、
そういうものを除いた最小限の使用例というのを記載し、
ディスクリプションには大まかには通常数段落でモジュールについて記述し、
モジュールのルーチンやメソッドの詳細、長めのコード例、
その他の深い内容については以降のセクションで説明すべきです。
理想としてはあなたのモジュールについて知っている人が、
ページダウンキーを押すことなく記憶を更新できるようにすることです。
読者がこのドキュメントを読み進めるにつれて、
徐々に多くの知識を得ることができるはずですというふうに言っています。
まあまあ、なるほどでしたね。
Synopsysセクションとディスクリプションセクションというのがパワールモジュールの書き方なんですね。
なるほど、そういう干渉になっているんですね。
はい、では続いて、人の時間に配慮をするというところですね。
素晴らしいことに、上記の重要な要素の順番点は、
誰かが賞としてどれだけ早くモジュールを放棄させるかによって決定されています。
ちょっと暗い話に聞こえますよね。
でも考えてみてください。
利他主義を念頭に置いた場合、あなたの仕事は、あなたの作品を売り込むこと、
例えばダウンロード数やユーザー数を最大化させることではありません。
あなたの作品が何をするものか、できる限り客観的に評価させ、
それが彼らのニーズを満たせるかどうかを判断してもらうことです。
この考え方は万人に受けるものではありません。
自身のエゴは抑えて、作品になるべく語らせる必要があります。
あなたの唯一の仕事は、その作品の約束ごとをできるだけ簡潔に説明することです。
そうすれば、モジュールのユーザーは、あなたの作品がニーズにマッチしたときに
使用するか、あるいは他の作品を探すかすることができますよと。
最後ですね。
妖精って書いてますけど、妖精ってどういうことやねん。
勇敢なるモジュール探索者より優れたドキュメントによって
あなたの作品を発見しやすく、使いやすくしてくださいというところですね。
一応今のが一つの区切りで、あとはここからおまけですね。
おまけなんで、どうしようかな。
おまけで読み切れそうな気がしますね。
ちょっといきましょう。
おまけです。
その他のグッドプラクティスですね。
本記事のキーポイントの他にも、READMEの品質の水準をグッド高め、
他の人にとっての有用性を最大化するために従うことができる、
あるいは従わなくても良いプラクティスが存在しますと。
いっぱいありますけど、11個あります。
一つ目ですね。
あなたのモジュールが重要だか、
だがあまり知られていない中小概念や他のエコシステムに依存している場合、
背景セクションというのを記載することを検討しましょうと。
例えば、Resecting Betweenというようなモジュールがあるんです。
というものがあって、
これの関数というのはその名前からすぐにわかるようなものではないので、
24:02
詳細な背景セクションというのを設けて、
これを使って説明することにするために必要な大きな概念や中小概念を定義して、
さらにリンクを押していますと。
また同様のモジュールがすでにNPMに存在する場合、
このモジュールを制作した動機というのを説明するのにも最適な場所になりますよと言ってますね。
場合によっては動機も必要かもしれないですもんね。
それを背景セクションというところに書くのは確かにいいかもしれないですね。
バックグラウンドですね。
じゃあ二つ目です。
二つ目は積極的なリンク化ですと。
他のモジュール、アイディア、人について話す場合は、
訪問者がより簡単にあなたのモジュールとモジュールの元になったアイディアを理解できるようにリファレンスをリンクにしましょう。
他の何にも依存しないモジュールはほとんどありません。
全てモジュールは他のモジュールに由来します。
ユーザーがあなたのモジュールの歴史とインスピレーションを辿るのを助けることはとても大切なことですよと言っています。
確かに依存しないモジュールってほとんど単純な関数なので、
それはもはやスニペットだと思いますもんね。
依存しない場合はその情報を含めましょう。
可能な限り慣例に従うことですと。
CBっていうのはコールバック関数、NUMっていうのはナンバーに意味するなどなどみたいなところです。
4つ目です。
使い方にあるサンプルコードってですね、
ユーセージのあるサンプルコードをリポジトリのファイルとして含めることですと。
例えばexample.jsみたいな。
ユーザーがリポジトリをクローンしたときに
readmeに記載されているコードを実際に実行できればそれは素晴らしいことですよねって言ってます。
これは僕も結構心がけてますね。
じゃあ5つ目です。
バッジの使用には慎重を期してくださいと。
乱用される恐れがあります。
例えばangularですね。
angularのリンクが貼られてます。
また、些細な議論や終わりのない議論の温床になる可能性もあります。
バッジはreadmeの視覚的なノイズになることに加え、
一般的なユーザーがオンラインのブラウザーであなたのmarkdownファイルを読んでいる場合にのみ機能します。
そうですね、オンラインで読んでいる場合に機能しますよね。
画像はほとんどがインターネット上のどこかで放送されているからですと。
それぞれのバッジについて考慮してみましょう。
このバッジはreadmeの一般的な読者にどのような価値を提供しているのでしょうか。
ビルドテストのステータスを表示する試合バッジはありますかと。
このステータスはメンテナーにメールを送ったり、自動的に作成したりする方が
重要な関係者は気づきやすいはずではないでしょうかというような問いも投げてますと。
readmeに記載されている情報の読者のことを常に考え、
その情報が意図した読者に最も届くようなフローを作れないのかを自問してみましょうと。
確かに結構無邪気にバッジ使いますし、使いたくなっちゃうし、
やっぱりバッジがあるとちょっとかっこよく見えるんですよね。
ドキュメント的にもしっかりされているようには見えますけど、
実際マークダウンファイルで見るとしたら、バッジのところってただのノイズなんですよね。
というところもあるので、ちょっとこの辺は悩ましいですね。
では時間30分になったんですけどちょっとなので、このまま走り切ってしまいたいと思います。
もしお時間がある方はこのままお付き合いいただければ嬉しいなと思います。
では続いていきましょう。
6話目ですね。
APIのフォーマットというのは些細な議論の的になり得ます。
最も分かりやすいと思われるフォーマットを使ってください。
ただしそのフォーマットが重要な細部というのを記述できていることを確認してくださいと。
27:00
その重要な細部というのは特に5つに分かれていますけど、
1つ目はどのパラメータが任意なのか、そしてそのデフォルト値は何なのかと。
2つ目に関連から明らかでない場合の型情報ですね。
3つ目ですけどOP2オブジェクトのパラメータがある場合は、
受け取るすべてのキーと値というのも書いてくださいと。
4つ目ですね。APIの関数の使い方が明白でない、
あるいは使い方セクションで完全にカバーできていない場合は、
小さなサンプルがあっても提供することをためならないことですと。
ただしこれはその関数が複雑すぎるという印でもあり、
リファクタリングやより小さな関数への分割、
あるいは完全削除する必要があるということでもありますので注意してくださいと。
最後ですね。
専門用語は積極的にリンク化しましょうと。
マークダウンファイルでは客注ドキュメントを一番下に記載しておくと、
ドキュメント中で何度でも参照したくなりますと。
APIのフォーマットに関する私の個人的な好みについては、
こちらのリンクがあります。
別のリンクがあるのでそれを見てくださいと。
今のが一応6番目のAPIのフォーマット表現というような議論ですね。
続いて7番目です。
モジュールがステートレス関数の小さなコレクションである場合、
関数の呼び出しと結果のノード、
REPLセクションですね。
セクションとして使い方を記載すれば
実行可能なソースコードファイルよりも
分かりやすく使い方を伝えることができるかもしれません。
なるほどね。
REPLセクションというのを、
ちゃんとリンクを貼られてますね。
一応イクザンプルのところが貼られてますので、
これも見てもらえると。
先ほど見たビスセクティングビトインという、
名前からよくわからないライブラリーの話ですね。
一応そういうセクションがあるというところでした。
続いて8番目ですね。
8番目は、モジュールがプログラム的にAPIの代わりに、
あるいはそれに加えてCLIを提供しているのであれば、
コマンドの呼び出しとその結果として
使用例をもちろん示してくださいと。
ファイルを作成または変更するようならば、
CATコマンドで変更前と変更後の状態というのも
示しておくと良いでしょうと。
これは良いですね。
9番目。
モジュールを探している人に見つけてもらうために、
パッケージJSONのキーワードを使うことを
お世話にしてください。
これは重要ですね、本当に。
文字列でずっとラレスできるので、
ここはしっかり書いておくと本当に良いと思います。
あとはGitHubのリポジトリにもキーワード載せられるので、
そこに載せておくのも全然良いと思います。
両方書いておくのがベストだと思います。
10番目です。
APIを変更すればするほど、
ドキュメントの更新に両力を割かなければならなくなります。
つまり早い段階でAPIを小さく
具体的に定義しておくべきだということです。
要件は時間とともに変化するものですが、
モジュールのAPIを事前に想定するのではなく、
モジュールセットという一番上の抽象化されたレイヤーを作りましょう。
もし要件が変わって特定のことをするだけでなくなったら、
必要なことをする新しいモジュールを書けば良いのです。
特定のことをするモジュールというのは、
NPMのエコシステムにとって有効かつ貴重なモデルであり続け、
軌道修正する際には、
あるモジュールを別のモジュールに置き換えるというような
単純な作業以外には何もコストはかかりません。
30:01
なるほどね。
これはちょっと設計的な話にも連なるけど、
確かに大事だと思います。
それができれば理想だなと思いますね。
最後、11番ですね。
最後に、バージョン管理されているリポジトリと、
その中のREADMEというのは、
リポジトリのホストやハイパーリンク先ですね。
特に画像ですね。
よりも長く存続することを覚えておいてください。
リポジトリのホストというのは、いわゆるGitHubのものですけど。
そのため、将来のユーザーがあなたの作品を理解するために
不可欠なものはすべて埋め込んでおくようにしてください。
ということでした。
おまけで、コモンREADMEというのがありますね。
偶然ではありませんけど、
コモンREADMEというリポジトリがありますね。
GitHubのリポジトリです。
コモンREADMEというのがあるんですね。
というREADMEのガイドラインと、
便利なコマンドラインジェネレーターでも
使われている形になっています。
これは偶然ではないんです。
もしこの記事に書かれていることが気になったら、
コモンREADMEを使えば、
READMEを書く時間を節約できるかもしれません。
この形式を使っている実際のモジュールの例も紹介されています。
また、スタンダードREADMEというのもあるんですね。
これもGitHubのリポジトリのリンクが貼られています。
こちらもおすすめです。
こちらはより構造化されていて、
リント可能な一般的なREADMEフォーマットになっています。
今回読んでいるこの記事は、
コモンREADMEというところに
わりとインスパイアされたような感じですね。
おまけとして、さらに実例がいっぱいバーッと載っていますので、
いろんな人たちの、いろんなライブラリの
実例のREADMEを見てみるといいと思います。
あとは、さらにおまけラストです。
READMEチェックリストというのも作っています。
READMEの完成度を測るのに便利なチェックリストというのがあって、
大体10個ぐらいありますけど、
ここら辺載ってあるといいんじゃないかということです。
今日読んだ記事をとりあえずガッとまとめて
チェックリストした感じですね。
改めて読みますと、
モジュールの目的を説明するワンライナー、
必要な背景情報やリンク、
見慣れない用語の有益なリソースへのリンク、
明確かつ実行可能な使用例、
あとはインストール方法、
豊富なAPIドキュメント、
コグニティブファネリングの適用、
注意点制限事項の事前説明、
重要な情報の説明を画像に頼らない、
最後、ライセンスですね。
はい、というところでした。
いろいろ書いてきたんですけど、
最後の著者の話だけバーッと載ってますので、
ここに著者の情報、
興味ある方は見てみてください。
主に3名ですね。
失礼、1名でした。
著者はノッフルさんという方ですね。
あとブログとかツイートとかハックとか、
いろいろなもののリンクを書いているので、
そこを見てみてもらったらいいんじゃないかな、
ということでした。
この小さなプロジェクトというのは、
5月にベルリンのスクワトコンフというのがあって、
そこで始まりましたと。
そこで私はパールモンクスというのが、
どのようにドキュメントを書いているかというのを
掘り下げていて、
またノードエコシステムのリードミーの状況を
ちょっと投げていましたと。
これがコモンリードミーを作る動機になりました。
コモンリードミーは、
この今日のドキュメントを書いた人本人の
作られたライブラリーなんですね。
そりゃインスパイアどころか本人でしたね。
リードミーチップスというセクションは
ヒントであふれるほどだったので、
リードミーの書き方について記事にまとめると
33:00
役に立つと判断して誕生したのが
このアートブリードミーという
ドキュメントだそうです。
なんか興味とか質問だったりコメントあれば
いつでもメールあげてくださいねという
往路でした。
あと客注だったりクレジットがバーっと
載ってますけど、
結構クレジットのリンク多いですね。
いろんな方に本当にレビューもらったんですね
というのがよくわかります。
というところで、
一応アートブリードミーという記事は
終了にしたいなと思います。
ちょっと時間かなりオーバーしてしまいましたけど
かなり学びがあったなというのもありますし、
やっぱりちゃんとリードミーを書いておく
というのは大事なことだなと思いますね。
未来について自分だったり他の人にも
いろんな人に対しても恩恵があると思うので
これをさらにここまでちゃんと言語化して
フォーマットしたりとか
チェックリストがあったりとか
というのはありがたいなと思うので
これぞOSSの活動の一つという感じはしましたね。
何もライブラリーにコミットすることが
OSSじゃないなという
一つの事例というふうに僕も感じました。
というところで、
じゃあ今日の朝活動は
こちらで以上にしたいかなと思います。
読むことに集中していたので
気づいたら結構多くの方に参加いただき
ちょっと恐れ多いですね。
参加いただきありがとうございました。
今日から1週間休みの企業さんの方も
いらっしゃるとは思いますし
学生さんもいるかもしれないですけど
仕事ある方は今日からまた1週間
頑張っていけたらと思います。
夏休みの方は暑いので体調気をつけつつ
ゆっくりとお休みいただければなと思います。
ではこちらで朝活終了したいと思います。
お疲れ様でした。
ありがとうございました。
