DevDocs: 複数の技術ドキュメントを1か所で検索できるドキュメントプラットフォーム

 (devdocs.io)
3 ポイント 投稿者 GN⁺ 2024-01-14 | 1件のコメント | WhatsAppで共有
  • 開発者がよく参照するAPIドキュメントを1か所に集約し、すばやく検索できるようにすることで、言語・フレームワークごとにドキュメントを行き来するコストを減らせる
  • デフォルトでは CSS、HTML、HTTP、JavaScript、Web APIs が表示され、Preferences で必要なドキュメントをさらに有効化したり、画面を調整したりできる
  • bgcp で background-clip を見つけられるあいまい一致と、ドキュメントごとの検索範囲指定により、目的の項目へより速くアクセスできる
  • マウスなしで使えるキーボードショートカット、ブラウザのアドレスバー検索、モバイル利用、Web アプリのインストールに対応している
  • オフラインでもドキュメントを閲覧でき、無料のオープンソースプロジェクトなので、開発環境に合わせて気軽に活用できる

複数の API ドキュメントを1か所で検索

  • DevDocs は、複数のAPIドキュメントを1つの高速で整理された検索インターフェースに統合している
  • 初期画面には CSS、HTML、HTTP、JavaScript、Web APIs のドキュメントが表示される
  • Preferences では、さらに多くのドキュメントを有効化したり、UI のカスタマイズを行ったりできる

検索とナビゲーションの方法

  • 検索はあいまい一致に対応している
    • たとえば bgcp と入力すると background-clip を見つけられる
  • 特定のドキュメント内だけを検索したい場合は、ドキュメント名または略称を入力した後、Tab で検索範囲を絞り込む
  • ブラウザのアドレスバー検索も利用でき、設定方法は ガイド で確認できる

キーボード中心の利用

  • マウスがなくてもナビゲーションと検索を進められる
  • キーボードショートカット の一覧を見るか、? を押して利用可能なショートカットを確認する

オフラインとインストール対応

  • DevDocs は オフライン でも動作する
  • モバイルで利用でき、Web アプリとしてインストール可能

無料のオープンソースプロジェクト

関連記事

1件のコメント

 
GN⁺ 2024-01-14
Hacker News の意見

  • 数少ない DevDocs メンテナーの一人です。
    ドキュメントシステムやデザインが丸ごと変わる場合でなければ、新しいリリースに合わせてドキュメントを更新するのは簡単です。ただし react.dev のリデザインのように、プロジェクトによってはこうした刷新をかなり頻繁に行うようです。
    一部のドキュメント生成ツールは、Gatsby が docs.npmjs.com で生成する .gtWOdv、.ezMiXD、.gOhcvK のような ランダムなクラス名を作るため、ページナビゲーションのような不要な内容を取り除く作業が面倒で不安定になります。
    毎月、古いドキュメントの一覧を自動生成しており、最新の一覧はこちらにあります: https://github.com/freeCodeCamp/devdocs/issues/2105
    支援はいつでも歓迎です。

    • simon04、ずっと昔にメンテナーの方々がしてくれた作業は、自分のキャリア、そして後には人生にも大きな違いをもたらしました。
      急ぎで引き受けたソフトウェアの仕事をしながら、通勤中に オフラインドキュメントを読めたことが本当に重要でした。
      devdocs を手伝っても一銭も稼げなかったかもしれませんが、実際の人々の役に立っていることをぜひ知っておいてほしいです。
    • このアプリは個人的にはかなりもどかしいです。最高のドキュメントソースの一つなのに、自分が選んだドキュメント一覧を保持できないせいで、ほとんど使い物にならなくなっています。
      ほぼ訪れるたびに、使っているスタックを最初から選び直さなければなりません。素晴らしいのですが、それを何度も繰り返すほど素晴らしいわけではありません。
      他の場所では Cookie やローカルストレージが消える問題はなく、最新の Linux Chrome を使っています。何か思い当たる原因はありますか？
    • ドキュメント生成ツールを 消費しやすさで評価してもらえますか？
      Sphinx、Docsy、MkDocs、Docbook などが、意味的に抽出しやすいという点でどう比較されるのか知りたいです。
    • 技術面接で、あるフレームワークで XYZ をどうやるかと聞かれたことがあります。
      正確には分からないが、devdocs.io で API インターフェイスを探しながら理解を深める、と答えました。
      面接官は意味が分からず、自分のノート PC で直接開いてみて、かなり驚いていました。
      もちろんその仕事は得られませんでしたが、面接テーブルの反対側に知識を広められたのはなかなか良いことでした。
    • このサイトが生き続けているのはこうした貢献のおかげで、その結果、Python 3.8 以降の自分の好きなアップデートについて発表してみたくなりました。
      データは自分でも探せたでしょうが、バージョンごとの比較を とても楽にしてくれます。

  • 数か月前に書いた「SWEs want offline docs」というブログ記事を見返しました: https://technicalwriting.tools/posts/offline-docs/
    ドキュメントが オフラインでの利用に適していることを知らせられる、RSS のような技術はありますか？ Service Worker のようなものではなく、ユーザーがドキュメントをオフラインで読めるようにする標準化された形式のことです。
    これまで見たのは、PDF と、ZIP にまとめた単体の HTML サイトくらいです。他に何かあるでしょうか？ まだまとまっていない考えですが、既に存在していて自分が知らないだけなのか気になっています。

    • ZIP より良いものがあるかはよく分かりません。私たちの Web サイト[0]にはゲームエンジンのドキュメントや Zig パッケージのドキュメントなどがあり、フッターに「offline version of this site」というリンクを置いて、約 80MB の ZIP ファイルを提供しています。
      ZIP の難しさは、ユーザーが画像をすべて欲しいのか、全バージョンのドキュメントが欲しいのか、それとも特定のバージョンだけが欲しいのかに合わせにくい点にあります。それでも ZIP が今のところ最善に見えます。
      [0] https://machengine.org/
    • 完全な答えではありませんが、オフラインドキュメントやローカル／オフライン利用向けテキストの標準は Markdown である、あるいはそうなってほしいと思っています。いずれにせよ私はほぼ常に Markdown だけで書いており、たいてい http://obsidian.md を使っています。
      ドキュメントをダウンロードする RSS 的なサービスとして、私が知っている最も近いものは Dash for macOS - API Documentation Browser, Snippet Manager - Kapeli です。
    • CHM[0] がまさにそれですが、Windows 中心です。ネイティブビューアでどう見えるかは、こちら[1]に例があります。
      Microsoft が諦めてしまったのは残念で、AutoHotKey のような一部のプロジェクトでは今も使われています。
      [0] https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help
      [1] https://www.helpsmith.com/images/ss/chm-help1.png
    • Zeal を使ってきました。まだすべてが揃っているわけではありませんが、かなり安心できます。
    • 私だけかもしれませんが、Emacs Info ドキュメントはこういう用途には本当に良く、邪魔にもなりません。

  • 長旅の前にチェックリストを見直しているところです。フライト中に開発したくなった場合に備えて、言語や API ドキュメントをダウンロードしているのですが、この素晴らしいツールを共有したいと思いました。
    多くの言語や API ドキュメントに簡単に オフラインアクセスできるようにしてくれます。Zig を少し復習し、Vulkan で何か面白いものを試してみるつもりです。よいお年を。

  • 移動中にプログラミングする際に役立ちました。特に WiFi が不安定なときに良いです。
    ドキュメントが一か所にまとまっている点も気に入っています。man、MDN、DevDocs が一つの標準インターフェイスに統合されれば、生産性は大きく上がりそうです。

  • プログラマーは厄介な問題に体系的な解決策を作るのが本業なのに、私たち自身の最も基本的なニーズはまだきちんと解決されていないようで、少し驚きます。
    たとえば DevDocs には、私がよく使うライブラリがかなり抜けています。Python 用 Selenium バインディングなどです。Dash も使ってみましたが、OpenAI のドキュメントのようなものをそのまま取り込めず、結局 Web サイトに行く必要がありました。
    つまり、構造化されたコンテンツを素早く検索できるという Dash の素晴らしい機能を奪われているわけで、かなり皮肉に感じます。

  • 最近の14時間のフライトでこれを使った。無駄になるはずの1日が、とてつもなく生産的な1日に変わった。
    邪魔が入らず、ときどき湧いた疑問にはドキュメントが答えてくれた。単に接続を切りたいときにも本当に良い。

    • すごく良さそう。時には、できることに制約があるほうが、かえって自由を与えてくれる。
      現代版のLinuxネットブックは何だろう？ Webを閲覧するには性能が低すぎて、集中せざるを得ない小さなマシンが欲しい。
      Chromebookがその座を占めたのかもしれないが、自分の生活にこれ以上Googleを持ち込みたくはない。

  • dedocは、CLIからDevDocsをダウンロードし、検索し、読めるオフラインCLIツール。ブラウザへコンテキストスイッチするのを避ける良い方法で、ブラウザ自体の誘惑も避けられる。
    https://github.com/toiletbril/dedoc
    Rustで静的コンパイルされているので、バイナリをダウンロードしてインストールすればよい。

  • オープンソース版Dash（https://kapeli.com/dash）みたい。いいね。

    • すでにオープンソース版Dashがある（https://zealdocs.or）。ただしDashの一部リストを使う契約のため、Macビルドは提供していない。
      それでもMacで自分でビルドできる（https://github.com/zealdocs/zeal/wiki/Build-Instructions-for...）
    • Linuxに戻ってから、Dashがとても恋しかった。やることリストにはWebベースのクローンを作ることが入っていて、Dashのキラー機能だったカスタムパッケージにも対応しようと思っている。
      ブラウザへコンテキストスイッチしなくて済むように、最高レベルのEmacs連携も入れたい。
      今は別のプロジェクトのリリースを先に進めているので、あとでまたやる必要がある。hexdocs.pmとMDNのタブを常に1つか2つ開いておかなければならず、生産性が大きく落ちている。
    • ユーザー投稿のドキュメントセットもある。Dashがホストしている: https://zealusercontributions.vercel.app/
    • Dashはreadthedocs.orgのドキュメントも本当に簡単に取り込めるが、DevDocsにはこの機能がない。

  • これは素晴らしい。もっと早く知っていればよかった。
    公式ドキュメントの結果だけを探していると分かっているときは、Web検索エンジンよりずっと良く、速度もはるかに速い。コピーを取得してローカルで実行するか、ホスティングしてみようと思う。

  • このツールが好きだ。Emacsパッケージ[1]として毎日使っていて、Dash系の解決策よりワークフローがずっと滑らかだと感じた。
    [1]: https://github.com/astoff/devdocs.el