Fork me on GitHub

JSer.info 10周年: JavaScript情報の集め方、書き方、まとめ方

Edit on GitHub 編集履歴を見る

JSer.infoは2011年1月16日に公開したJavaScriptの情報サイトで、2021年1月16日で公開してからちょうど10年です。
JSer.infoでは、10年間で10201サイト紹介し、522コの記事書いてきました。

JSer.infoの紹介したサイト数

JSer.infoの紹介したサイト数(累計)。ソース

10年間途切れることなく毎週更新していて、月別の記事数は毎年同じ推移です。

JSer.infoの月別の記事数

JSer.infoの月別の記事数。ソース

この記事では、10年間やってきたJSer.infoの目的を振り返り、
JavaScriptの情報の集め方、書き方、まとめ方について書いていきたいと思います。

⚠️ すべてを書いているのでものすごく長いです。

この記事やJSer.infoに関する意見や感想などは、次の場所に書いてください。

目次

JSer.infoの目的

JSer.infoについて - JSer.infoに、JSer.infoを始めた経緯を書いています。
JSer.infoの目的をあらためて振り返ると次のようなものです。

  • 「JavaScriptに興味がある人にもっとJavaScriptを知ってもらう」
  • 「JavaScriptの情報を整理して正確に伝える」
  • 「更新コストを小さくして継続できる形を作る」

この目的ごとに、今のJSer.infoを振り返ってみます。

「JavaScriptに興味がある人にもっとJavaScriptを知ってもらう」

JSer.infoではJavaScriptの最新の情報を扱うことにしています。
最新の情報として分類する時に使える切り口(ファセット)としては次のようなものがあります。

  • 日付(正確)
  • 新規性(やや曖昧 - 過去に類似するものがあるかの調査が必要)
  • トレンド(曖昧 - 人/世の中への依存)

いつリリースされたかいつ公開されたかという日付は一番で正確で曖昧性が低いです。
そのため、JSer.infoでは情報をまとめる時に {YYYY}-{MM}-{DD}のJS という週単位の記事でまとめています。

公開された記事やライブラリが今までなかったものであるかという新規性は、実際に調べてみることである程度わかります。
流行り廃りのようなトレンドは、主観的な話題が混ざるため曖昧になりやすいです。

JSer.infoには「JavaScriptの情報を整理して正確に伝える」という目的もあるため、
曖昧なものより明確なものを好んで扱っています。

人によって欲しい情報は異なる

JSer.infoでは最新の情報を扱うという話でしたが、人によって欲しい情報は異なります。
これは、その人が「新しい情報」なのか「トレンド」なのか「安定して使えるもの」といったどういう情報が欲しいかによって、情報の読み方は異なります。

技術的な情報には受け取りたい情報によって、いくつかレイヤーがあると思います。
次の図は、「新しい情報」や「新規性」という切り口(ファセット)で、そのJavaScriptの情報を受け取れる場所?をレイヤーに分類してみた図です。

技術情報のレイヤー

JavaScriptの情報を「新しい情報」という視点でレイヤーを分けた図。
実際にはレイヤーは重なるし、レイヤーの中身は人や求める情報によって異なるはずです。

たとえば、「JavaScriptの新しい情報」がほしいなら、Awareness(認知)のレイヤーの情報を見た方が新しいものは見つかりやすいです。
今現在(2021年)ならGitHubが圧倒的な元ソースとなっているので、GitHubを上手く見る方法が必要です。
欲しい情報によって何がソースになるかは変わってしまうので、最新のJavaScript情報はGitHubに多いという話でしかありません。

JSer.infoのドメイン別での紹介数の推移

JSer.infoのドメイン別での紹介数の推移の図。

GitHubの比率が大きい。ソース元データ

何が流行っているのかという「JavaScriptのトレンドの情報」が欲しいなら、Interest(興味関心)のレイヤーの情報を見るのが良いかもしれません。
具体的には、どういう人が使ってるのか見聞きしたり、ブログで利用事例を読んだりするのが、トレンドという曖昧なものを見るのには良いかもしれません。
Aggregationのように複数のソースをある興味軸(カテゴリやタグ)などで分類して見るのも良さそうです。

安定して実践的に使えるJavaScriptの情報が欲しいなら、Comparison(比較検討)のレイヤーの情報を見るのが良さそうです。
ここには書籍、雑誌、メディアのような比較検討して整理された情報がありそうです。
このレイヤーの情報はまとまるまで時間がかかるというデメリットもあります。
一方で、最近はアグリゲーションのように単に集めるだけではなく、そこから更にカテゴライズ/フィルター/注釈などをして情報をより整理したものもあります。
書籍、動画講座なども短いサイクルで逐次的にリリースしていく試みもあります。

JSer.infoの情報の集め方

では、実際にJSer.infoではどのように情報を集めているかというと全部のレイヤーを見ていますという答えになってしまうので、もう少し掘り下げます。

基本的には情報をRSSとしてInoreaderに集めて、Irodrで見ています。

数にはあまり意味はありませんがRSSフィードの購読数は、2012年ごろは2000前後2014年ごろは2800前後2017年ごろには3200前後2020年ごろには2600前後でした。
この間にRSSフィードの管理方針は大きく変えていませんが、404となったりしたRSSフィードの購読を解除しています。(そのため減ったりしている)
興味があるものについてのRSSフィードを増やしても、線形的に登録数が増え続けるのではなく、実際に更新されるものはある程度の数に収束しています。

現在の購読しているRSSは3600前後です。これは、最近watch-rssによってリポジトリのリリースRSSを自動的に追加するようにしたため、+1000ぐらい増えています。実際には毎日数個のリポジトリが更新される程度なので体感はほぼ変わらないです。

どのようなものをみているかを、レイヤーごとに簡単にリソースを書いてみます。
実際にはその他にあたるような個別のブログや人が情報源となる場合が多いでしょう。

📝 JSer.infoでここ最近紹介したサイトを回数で分類したデータは、JSer.info Watch Listで参照できます。
このリストに出てくるサイトは個別のRSSを登録していると思って間違いではない気がします。

⚠ 注意: ここでの情報の集め方は、最新の情報を集めるためという目的を元にしています。
そのため、別の目的の場合はこの集め方が適切ではない可能性が高いです。


GitHub

JSer.info Data Dashboardによると、
2020年の合計紹介アイテム数は810で、そのうちgithub.comをソースとするアイテムは308コです。

JSer.infoで紹介したドメイン at 2020年

JSer.infoで紹介したドメインの比率 @ 2020年。 ソース

つまり、JSer.infoの30% ~ 40%程度はGitHubが元情報となっています。
そのため、(逆説的でもありますが)GitHubを色々な方法で見ています。

トレンド

GitHubにはTrendingがあるので、これをRSSで見ています。
今年のオープンソース活動振り返り @ 2020にも書いていましたが、GitHubのトレンドは一度のると複数日継続することが多かったり、どこかで話題になったものが載りやすいです。
そのため、新規性や人気というよりは話題の収集に近いかたちだと思います。

イベント

GitHubでWatchしているリポジトリはだいたい2000ぐらいあり、半分は自分のリポジトリなので、1000リポジトリぐらいをWatchしています。
このぐらいの数になるとNotificationで見るのは不可能であるため、GitHubの通知(privateは除く)をタイムラインの概念がある別の場所に流してみています。

今は、github-to-discordでDiscordに流して、TwitterとDiscordをPhoenix並べてみています

TweetDeck and Discord

このイベント情報(Star、Issue、Pull Request、Releaseなどがごちゃまぜ)は、実際に見ても流量が多くて得られる情報はほとんどありませんが、
雰囲気を感じるために流しているという感じです。(実際に全部見ているわけではないです)

たとえば、TypeScriptnodeなどは単独のリポジトリとしても大きすぎてWatchするのは難しいですが、イベントを流しているとたまに目に入ったことから今やっていることに気づくことがあります。
Twitterよりさらに雑にGitHubを雰囲気で読む感じだと思います。

リポジトリ

  • User、Organizationに新しいリポジトリが作られたとき
  • 検索結果にリポジトリが増えたとき
  • フォローしている人がスターしたリポジトリ

RSSHubはいろんなサイトのRSSを生成できるサービスですが、GitHubの色々な情報をRSSにできます。

たとえば、ECMAScriptのProposalはhttps://github.com/tc39にProposalのリポジトリを作る/移管するため、
https://rsshub.app/github/repos/tc39を購読していれば、ECMAScriptの新しいProposalに気がつけます。

他にもWeb Incubator CGを見ていれば主にChromeの新しいWeb Platform APIを気づけますし、
Privacy Community Groupを見ていれば、Privacy系の新しい仕様に気がつきます。
これは、現在のウェブ標準のプロセスにGitHubが絡んでいることが多いので、プロセスがわかっているものについては効率的に把握しやすいです。

また、FacebookGitHubMicrosoftなどの企業のリポジトリ新着を見ていると面白い技術に会えたりもします。

その他には、starseekerを使うとGitHubでフォローしている人がStarしたリポジトリをまとめて見れます。
フォローしている人はだいたい興味が同じだと思うので、興味があるリポジトリを見つけやすいはずです。

リリース情報

  • Watchベースのリリース情報のRSS: watch-rss
  • Starベースのリリース情報のRSS: Bandito.re

JSer.infoではライブラリなどのリリースノートを良く扱います。
ライブラリのほとんどはGitHubでリリースされているので、GitHubリポジトリごとのリリースRSSフィードを購読するのが確実です。

  • https://github.com/{author}/{repo}/releases.atom にリポジトリのリリースRSSフィードがあります

以前似たような話を書いていましたが、最近はGithubのWatchで"Release Only"が選べるようになったので、Watchしているリポジトリのリリース情報を自動でRSSとして購読する仕組みを作って見ています。
watch-rssは、WatchしているリポジトリのリリースRSSをInoreaderで自動的に購読するツールです。そのため、今はWatchしたら自動的にRSSフィードに登録されて、RSSリーダで新しいリリースに気づけます。
リポジトリ個別のRSSフィードなので、興味がないリポジトリ(またはmonorepoのような大量リリース)はスキップすればいいだけなので、リリース情報だけをみるのは効率が良い感じはします。

watch-rssBandito.reを参考に実装しました。
Bandito.reは、Starしたリポジトリのリリース情報をまとめたRSSフィードを作成してくれるサービスです。

自分は、GitHubリポジトリを既読管理ぐらいの気持ちでStarを押してしまうので、量が多すぎてちゃんと見れるものではないですが、たまに昔Starしてものが出てきて発見できます。

検索結果

検索結果の購読は最も難しいです。
"JavaScript"のような単語で見ても、ほとんどがノイズとなって意味がある情報は見つけられません。

PMAlertsKarma - 5 social listening tipsという話にもありますが、検索結果を見る場合には"網ではなく槍を使う"という話があります。
具体的には、かなり検索結果が絞られるように検索ワードの組み合わせを見ていく形にしないとまともに機能しません。

"JavaScript" ではなく JavaScript Lightweight" のような範囲が絞られるようなワードにしないとノイズだらけになります。
たとえば、ある会社の情報をGoogleアラートなどで追いたいなら "CEOの名前 会社名" などを検索したものをメールやRSSで見るといった形です。
(重要な決定や考え方などはだいたいCEOがインタビューなどで答えているので、そのような記事がかかりやすくなる)

検索結果を追うのは難しいので、自分はそこまで受動的に検索結果を見ていません。

SNS

  • 無限にあります

📝 @jser_infoのTwitterアカウントは、Realtime JSer.infoの更新と記事が投稿されたことを通知します。

Daily/Weekly/Montly

Cooper Press PublicationsJavaScript WeeklyなどのWeeklyのニュースサイトをやっている会社です。
JavaScript WeeklyはJSer.infoの少し前に始まったメールマガジンで、今でも続いているサイトです。
(Meta Weeklyにこのようなサイトをまとめていましたが、増えたり消えたりして整理できなくなりました。)

この辺のニュース的なサイトは積みやすい感じがするので、自分のペースとリズムに合うものを探すのが良さそうです。

アグリゲーション/ソーシャルブックマーク/ソーシャルニュース

この辺は複数のRSSをまとめるアグリゲーションサービスや、はてなブックマークのようなソーシャルブックマーク、Hacker News(HN)のような投稿と投票の機能をもったソーシャルニュースなどのコミュニティ系のサービスです。

どのサービスも共通している気がしますが、量が限定されている場合には質が良いと感じ、量が増えていくと質が悪くなっていくと感じる気がします。
これは情報の量が増えると、求める情報とは異なるものも入ってきやすいからだと思います。(もしくは求める情報の種類が変わったのかもしれません)
そのため、これらのサイトは自分の価値観に合うようなフィルターをもって見るのが良いと思います。

たとえば、Topic Deckは色々なRSSをまとめたアグリゲーションサイトです。
ディレクトリ的な階層型のトピックを見る仕組みですが、上位のトピックは量が多すぎて見るのが難しいと思います。
少し下の階層まで絞り込んでWeb Browser Engのようなブラウザベンダーに関するトピックに限定すると機能するイメージです。

同じように他のサイトも、広すぎる範囲で見ようとすると破綻するので、なにかしらの方法でフィルタリングできたほうが情報量と質をコントールできると思います。
たとえば、はてなブックマークならお気に入りユーザー機能を使う、Twitterならリストを使うなどです。

📝 自分はIrodrでレートで分類して読んでいるので、
スキップしてもいいんだなぐらいの気持ちで眺めるために情報量が多いトピックも購読していることがあります。

その他には、Slackなどで特定のコミュニティに入ってみる方法もありそうです。
JSer.infoのslackでも、JavaScriptの情報を投稿してたりするので、興味がある人は見てみると良いかも知れません。
次のリンクから誰でも参加できます。

ブログ/サイト

  • 無限にあります

JSer.info Watch Listというサイトに、ここ数年で一度でもJSer.infoで紹介したことあるサイトを一覧できるようになっています。
タグ別にフィルタリングもできるので、興味の分類で気になるサイトを見つけることができるかも知れません。

JSer.info Watch List

その他には、State of JS 2020: Resourcesのアンケート結果に有名所は並んでいます。

ブログは個人サイトではなくQiitaやMediumなどのサービスで書いている人も多いです。

これらのサイトはタグや人単位でRSS購読できるようになっています。
タグを購読する場合、最初のうちはタグでみるとちょうど良いのですが、やはり記事の流量が増えてくるとタグという網が崩壊します。

たとえば、MediumのJavaScriptというタグを購読するのは無謀だと思います。
この場合は、別の方法で見たり、RSS自体を加工したり、RSSリーダ側でフィルタリングするなどの工夫が必要そうです。

書籍

あまり追いかけていませんが、最近はGoogle Books APIの検索結果をRSSとして読めるツールを作って、新着の書籍を見ています。

また、Oreilly(日本と英語)はどちらもまとまったものがあるので見ています。

しかしながら、最近は出版物ではない技術書もあると思うので、そういうのは見つけにくいかも知れません。


他にも過去にいろいろな情報の集め方について書いています。

ベースにRSSを置くところはずっと変わっていませんが、何をRSSで見ているかは度々変わっています。
これはRSSを使って受動的に情報を集めるために、能動的に仕組みを作ってるという話でもあります。

あるサービスに依存した収集だと、そのサービスや価値観が変わり「なんかだめだな」と思った時に、仕組み自体を変える必要があるためコストは大きいです。
RSSの場合は、なんかだめだったら、フィードを解除するだけでいいので気楽です。
少しモジュール的な感じになっていて、新しい仕組み(RSS)に移動するだけなので単純です。

自分は偶然的な出会いのためにRSSを使ってる部分もあります。
たとえば、npm addictを購読しているのですが、このRSSはnpmパッケージをRSSとして流しています。
ほとんど絞り込みがないnpmの新着なので、検索結果のRSSのようにあんまり意味があるものを見つけられることはほとんどありません。
普段は低いレートのフォルダに入っているのでスキップしてるだけです。

あるときnpm addictを見ていて、偶然@webという面白い名前のパッケージがpublishされたことに気づいて、Introducing: Modern Webにたどり着いたことがあります。
こういう偶然の発見もあったりしますが、あまりおすすめはしません。

JavaScriptにかぎらず情報収集は、自分が欲しい情報に合わせた見つけ方が必要です。
また、同じサイトやサービスを見ていても、手に入る情報やその価値は変化してきます。
そのため、今の自分に合わせた情報の集め方が必要になると思います。

JSer.infoでは、これらの集めた情報を使って、質と量が安定した記事となるように更新しています。
これは、2つ目の目的である「JavaScriptの情報を整理して正確に伝える」ためです。

単純に集めた情報を流すと量と質のバランスに問題がでるため「JavaScriptの情報を整理して正確に伝える」ことが難しくなります。
実際にJSer.infoではどのようなことを意識して情報を整理しているかを見ていきます。

⚠ この記事は、普段の投稿と違っていろんなバランスを無視して詰め込んでいます。

「JavaScriptの情報を整理して正確に伝える」

JSer.infoでは、2-3行の説明文とともにサイト(URL)を紹介します。
この説明文は、サイトの内容を検証してどのような言葉を使って、どのような言葉は使わないで説明するかを考えて説明文を書いています。
以前、JSer.infoの作り方というスライドでも紹介しています。

10年間で、10201のサイトを紹介し、合計で71万文字の説明文を書いています。
そのため、このサイトの内容をどうやって整理して説明文にして伝えるかという部分についても、ある程度考え方がまとまってきました。

今回は10周年を記念してJSer.info Policyという形で、情報を整理して正確に伝えるためにどのような考えでやっているかを明文化してみました。
明文化するにあたっては、DoとDo Notに分けています。基本的には何をするべきかというDoの考え方で整理しています。Do Notで書くと無限に増えてしまうためです。


JSer.info Policy

JSer.info Policyでは「JavaScriptの情報を整理して正確に伝える」という目的を満たすための考え方を書いています。

ここでの用語は次のような意味です。

  • 元サイト
    • 紹介する予定の元データとなるサイト/記事/動画/書籍などのこと
    • サイトではないこともあるがまとめて"元サイト"と呼ぶ
  • アイテム
    • 紹介する元サイトのURLやそれに関する説明文、タグ、関連URLなどをまとめたものを1つのアイテムと呼ぶ
  • 記事
    • JSer.infoに公開している記事のこと
    • 記事はアイテムをまとめたもの

Do

情報を整理して伝えます

JSer.infoでは、元サイトからアイテムを作成する際には、元サイトの内容を整理します。
整理とは、元サイトの内容を抽出、要約、補足、言い換え、グルーピングなどの分かりやすくするための作業のことです。

整理は、元サイトの内容を解釈の揺れが起きにくい形にし、元サイトの概要をわかりやすく伝えることを目的にしています。

整理には元サイトのすべての内容から一部を削ったり、別の言い方への変更も含まれます。
元サイトの内容をすべてそのまま伝えることは目的ではありません。
詳しくは、「元サイトのすべてを伝えるのは目的ではありません」を参照してください。

整理に関する作業

  • グルーピング
    • リリースノートならmajor/minor/patchを意識してまとめる
      • 破壊的な変更、機能追加と修正でまとめる
    • 種類でまとめて順番に見れば分かる形にする
  • リリースノート
    • 意見と事実を分ける
    • 具体的なコードの変更を対応付ける
  • 元サイトの目的
    • 元サイトの目的を明らかにして伝える
    • 現実の実装と目的が離れているときがある
  • 行き違いのある言葉を減らす
    • 軽量、互換など解釈の違いが起きやすい言葉に補足を加える or 置き換える
    • 互換性はどこまで目指しているのかという目的に置き換える
    • 軽量は具体的に何が(サイズ、パフォーマンス)軽量なのかを分かるようにする または 具体的な数字へと置き換える
  • 関連リソース
    • 関連する/依存するリソースを関連アイテムとしてまとめる

事実とフェアネスを追求します

JSer.infoでは、事実を検証してフェアネス(公平性)の追求に努めます。

元サイトの技術的な内容を検証し、その内容が事実であるかを確認します。
内容を整理する際には、中立で客観的であることに注意を払いフェアであることに努めます。
ただし、事実であってもデータが不完全であることから、統計的差別などが含まれている可能性があることに注意します。

また、アイテムは誰もがアクセスできるデータに基づき整理します。
これは、誰もが同じデータを検証できることがフェアであるためです。

アイテムや記事として整理したものに訂正すべき間違いやフェアネスを逸脱する内容については、速やかに訂正します。
詳しくは、「完成していないことを受け入れます」を参照してください。

事実とフェアネスに関する作業

  • 技術的な嘘はつかない
    • 技術的な嘘は目立つため検証の手間を省かない
  • 誇張表現をそのまま捉えない
    • 伝聞して拡散する役割ではない
    • 事実を検証して整理する
  • 事実によるデータの差別は避ける
    • 統計的差別のように元データが不完全であるため、その事実が見えている可能性があることに注意する
    • トレンドデータ
      • トレンドデータについては曖昧性が含まれていることを意識する
      • 日付(正確)
      • 新規性(やや曖昧 - 類似の調査が必要)
      • トレンド(曖昧 - 人/世の中への依存)
    • アンケート
      • アンケートには回答者によるデータの偏りが発生しやすい
      • アンケートの回答者の地域によっても差が出てくることがある
      • アンケートの結果については、元データに対する注釈を入れる または アイテムとする時にデータに対する結論に対しては扱わない(読み手の解釈に委ねる)など
  • 人が容認できない言葉を避ける
    • ジェンダー、差別、FUDなど、ただの差別になっていかを確認する
    • アイテムがコントリビューター行動規範に反した内容ではないかを確認する
    • 主観を取り除くことは難しいため、指摘は速やかに受け入れる
  • 偏り
    • 意見の偏りを常に意識する
    • 客観的に整理する
    • 意見そのものが悪いわけではないため、記事としてバランスを意識する
  • Public/透明性
    • 元サイトなどについては、誰もがなにかしらの方法でアクセスできる情報のみを扱う
    • 招待されないと見れない or 特定の人のみが見える情報をベースにして書かない
    • これはデータの偏りを少なくためにも注意を払う
  • 比較する場合の事実と再現性
    • ベンチマークは注意して事実を検証する

情報源に敬意を払います

情報源となる元サイトに敬意を払います。

情報の本質は元サイトにあるため、JSer.info単独では完結しません。
JSer.infoの目的は、元サイトを見てもらうことを促進することにあります。

クロスポストされている場合には、できるだけオリジナルのものを元サイトとして扱います。
翻訳に関しては、翻訳内容が元サイトを尊重しているかを確認してから元サイトとして扱います。

また、元サイトのさらに元となる情報源がある場合には、関連リンクとしてその情報を含めます。

情報源に関する作業

  • 目的はJavaScriptの情報を”紹介”ではなく”知ってもらう”事にある
  • 媒体の特性を見る
    • クロスポストサイト
      • できるだけクロスポストの作者オリジナルの記事を元サイトとして扱う
    • 転載
      • 作者オリジナルの記事を元サイトとして扱う
  • 翻訳
    • 翻訳がライセンスは正しいかを確認する
    • 翻訳が元の内容を逸脱するようなタイトルや内容に変更してないかを確認する
    • 翻訳の原文に対するリンクをアイテムの関連記事として入れる
    • 原文と翻訳がほぼ同時に公開されている場合は、原文を元サイトとして扱う
  • 元サイトの元
    • 元サイトのさらに元サイトがあるなら関連リンクとして扱う

完成していないことを受け入れます

JSer.infoは、JSer.info単独で完結するサイトではありません。
記事やアイテムにはさまざまサイトに依存した内容が書かかれているため、どの段階でも訂正や変更が入る不完全な状態です。

元サイトの内容を整理する際には、解釈の間違いや誤記などが発生する可能性があります。
アイテムや記事における間違いの指摘は、速やかに受け入れ訂正する必要があります。

完成していない作業

  • 単独で完成していないことを意識する
    • 膨大な情報を無理やりまとめて完成させようとすると、他のポリシーを逸脱しやすいことに注意する
  • 間違いの訂正は速やかに受け入れる
    • 解釈の間違いが発生することはある
    • どのタイミングでも、修正を受け入れることができるようにする
    • jser/jser.info
      • アイテムのデータを修正したい場合
    • jser/jser.github.io
  • 分からないものを独自解釈しない
    • わからないものはわからないものとして扱う

Do Not

元サイトのすべてを伝えるのは目的ではありません

JSer.infoは、翻訳サイトではありません。
そのため、元サイトの内容を一字一句正確な対訳で紹介することは目的ではありません。

元サイトの内容を複製して伝えるのは目的ではありません。
元サイトの内容を整理して伝えることが目的です。

元サイトのすべてを完璧に伝えようとすることは目的ではありません。
すべてを伝えることを目指してしまうと、単なる複製になってしまいます。

元サイトのすべてを伝えない作業

  • 翻訳するのは目的ではありません
    • 一字一句正確な対訳を作ることは目的でありません
    • これは他のポリシーに反してしまいやすい
    • 情報を整理することを考え、取捨選択することを意識します
  • 元サイトの内容を複製するのは役割ではありません
    • JSer.infoにすべての情報が集約される必要はないため、情報をすべて複製する必要はありません
    • JSer.infoの目的は、紹介することではなく、知ってもらうためです
    • そのため、必ずしもユーザーはJSer.info自体を見る必要はありません

これらのことはJSer.info Policyというドキュメントにまとめてあります。

このポリシーをまとめるためのメモ書きは次のリポジトリのIssueに書いています。
Issuesを見てみるとわかりますが、だいたいDo Notの形になっています。
使わない言葉とかの方が具体的ですが、少し詳細になりすぎていたので、JSer.info Policyではやることという形式で書き直しています。

「情報源に敬意を払います」というポリシーにもありますが、JSer.info自体が情報を作っているわけでありません。
継続して新しいライブラリ、記事、プロダクトを作っている人たちがいることによって成り立っています。
JSer.infoがこれらの継続した情報を伝えるためには、JSer.info自体が継続しやすい形になっている必要があります。

このことは、「更新コストを小さくして継続できる形を作る」というJSer.infoの目的にもなっています。
最後に、3つ目の目的である「更新コストを小さくして継続できる形を作る」を見ていきます。

「更新コストを小さくして継続できる形を作る」

JSer.infoを開始した時にとりあえず2年は続けると決めていました。
これは継続的にやらないと、JavaScriptに興味がある人にもっとJavaScriptを知ってもらうことやJavaScriptの情報を整理して正確に伝えることが難しいと考えたためです。
また、その継続コスト自体を下げていく必要性があるために設定した目標です。

JSer.infoの更新ワークフロー

現在の更新ワークフローは、次の図のようなサイクルを1週間ぐらいの単位で繰り返しています。

JSer.info Workflow

  1. 見る
  2. 調べる
  3. 検証する
  4. 説明文を書く
  5. 1 ~ 4を繰り返して一定数ためる → 共有(記事を書く)

このサイクルについては、次のスライドや記事でも解説しています。

もう少し具体的な行動を書き出してみると、1サイトごとに次のようなことをやっています。

例) Nullstackのケース

今のワークフローは、少しでも面倒さを感じたら自動化しています。

例えば、初期のJSer.infoでは、次のようなワークフローで記事を更新していました

  1. アイテムデータ(紹介したいサイトのデータ)を追加
  2. 投稿前に、それぞれのアイテムを"アーティクル"とか"スライド"といったように手動でカテゴライズ
  3. 投稿用のHTMLデータを作ってコピペして、ヘッドラインを書き足して記事を作成する
    • この時にTumblrのエディタ画面は使いにくかった、別のエディタアプリで編集したりしていた
  4. 投稿

初期のJSer.infoの更新作業

実際の動作はJSer.infoのアーカイブで見れます

現在では、次のようにCIが面倒な部分を自動化してくれるワークフローになっています。

  1. jser/jser.infoに対してアイテムデータ(紹介したいサイトのデータ)をコミットする
  2. CIが次の投稿用の記事のドラフトとなるMarkdownファイルを作成して、jser/jser.github.ioに対してpushする
  3. Pull Requestをブラウザ上で作って、Pull Requestの説明文を書いてマージ
    • Pull Requestのタイトルや説明欄を元に、ドラフトのMarkdownファイルに更新するGitHub Actionsを動かしている
  4. マージすると自動的に投稿される

今のワークフローではメモを書くところ以外は、ブラウザ内で完結しています。
メモを書く作業は、色々なタブを行き来しながら書く必要があるため、Floating Windowでメモをサイトに重ねて書けるPostemを使っています。

本当に人間がやることは、紹介したいサイトの説明文とタグを付けるのと、あとは記事のヘッドラインを書くだけです。
どういう並び順で、どういうカテゴライズするかは過去のデータから学習して自動化されています。

更新コストの削減

何かを続ける意欲を維持できるかは、続ける理由とやめる理由のバランスの問題です。
やめる理由が続ける理由よりも大きくなれば、そこでやめてしまうと思います。

情報収集自体はJSer.infoとは関係なく、良いコードを書くためするので、続ける理由については大きな変化はありません。
そのためJSer.infoでは、やめる理由を小さくしていくことで、継続するためのバランスをとっています。

そのために、更新ワークフローの自動化をしています。
また、GitHub上で完結させることによって、アプリの切り替えといったコンテキストスイッチが発生しにくいような構造にしています。

これらの自動化などはJSer.infoを更新しながら、面倒なところを徐々に修正していたら今の形になりました。

HubMemo

この長い記事をここまで読み進められた人は、おそらく自分と同じことができると思います。

10周年を記念して、JSer.infoのような仕組みをワンクリックで作れるHubMemoというシステムを作りました。

HubMemoは、GitHub上にメモをコミットすると、そのメモをまとめたものを記事として公開する仕組みをまとめたテンプレートリポジトリです。
つまり、jser/jser.infojser/jser.github.ioでやっている仕組みを一つのリポジトリにまとめたものです。
内部的には、色々なGitHub Actionsを使って、メモをコミットする仕組みや、メモから記事を作る仕組みを持っています。

JSer.infoのようなサイトだけじゃなくて、ただのGitHubを使ったメモの仕組みとしても使えます。

HubMemoのセットアップ

HubMemoはテンプレートリポジトリなので、リポジトリを作るだけで準備完了です。

  1. Use Templateから、HubMemoを元にしたリポジトリを好きな名前で作成する
    • メモは非公開で、記事だけ公開したいならPrivateリポジトリでも作れます
  2. GitHub + Jekyllの場合は、リポジトリのBranch: main > /docsがGitHub Pagesとして公開されるように設定します
  3. Jekyllを使って記事を公開する場合はこれで完了です!
    • Jekyll以外で公開する場合は、Setup Guideを見てください

HubMemoにメモを追加する

HubMemoは色々な方法でメモファイル(JSONとMarkdown)をコミットできます。

  • GitHub ActionsをHTTP API経由で叩いてメモを追加する方法
  • Gitでファイルをコミットする方法
  • GitHub ActionsのGUIを使って追加する方法
  • Issueを作ると、そのIssueの内容をメモとして追加する方法
  • JSer.infoで普段使っているpostemというGUIアプリを使った方法

詳細はUsageのドキュメントを見てください。

HubMemoのメモから記事を公開する

HubMemoでのメモはJSON(機械用)とMarkdown(人間用)の形式でそれぞれ追加されます。
JSONはツールが処理しやすい形式で、Markdownは人間がメモを読むための形式です。
(📝 JSer.infoでもJSON形式でメモを作っていたことで、自動化や統計処理ができていたのでJSONで持っています)

メモが追加されると、自動的に記事を公開するドラフト用のPull Requestが作成されます。

  1. メモをIssue経由で追加: https://github.com/azu/hubmemo-sandbox/issues/7
  2. メモを追加すると、メモを含むドラフトPRを自動的に作成: https://github.com/azu/hubmemo-sandbox/pull/8

あとはこのドラフトPRのファイルを更新して、マージすれば自動的にGitHub Pagesにブログとして公開できます。
(📝 HubMemoはJSer.infoと同じようにPRのタイトルや説明欄を更新すると自動的にファイルと同期します)

HubMemoは、JSer.infoのワークフローのエッセンスを取り出したシステムです。
HubMemoを使って、自分用のメモを書いてみるのもいいし、それを整理して公開してみるのもよいと思います。

また、HubMemoはGitHub上ですべて完結しているため、普通のオープンソースのようにコラボレーションしやすい気がします。
JSer.infoも基本的にはGitHubで完結しているので、JSer.infoでのコラボレーションに興味がある人は、@azu_reJSer.info slackを訪ねてみてください。

おわりに

JSer.infoは開始から10年経ちました。
JSer.infoがJavaScriptに関する少し整理した情報を提供することでより良い流れを作れているなら幸いです。

この記事では、JSer.infoの目的であるJavaScriptに興味がある人にもっとJavaScriptを知ってもらうJavaScriptの情報を整理して正確に伝える更新コストを小さくして継続できる形を作るに対してどのように取り組んでいるかの現状を書きました。

最近では、JSer.info slackGitHub Sponsorsを始めたりしています。

JSer.infoへの意見や感想などがあれば、次の場所に書いてください。

JSer.infoは、「JavaScriptの情報を整理して正確に伝える」とあるようにどこからか発信された情報を伝える役割を持っています。
次は、そのような情報を受け取った人が情報を発信する(発信側へとなる)ために何ができるかを考えていきたいです。

JSer.info?

この記事へ修正リクエストをする
JSer.info Slackに参加する