公式ドキュメントのユースケース

次のようなセクションがあった場合、何を読むかというのはその目的によって異なるという印象。

Getting Started: インストール、セットアップ
Tutorial: 基本的な使い方(代表的な使い方)
Concepts: デザインのコンセプト、なぜ作ったか
Examples: 動くサンプル
API Reference: APIのリファレンス

目的によっては、公式ドキュメントじゃない方が理解しやすい場合もあります。

ただし、公式ドキュメントに書かれていることが大体のケースでは正確なので、どの目的の場合でも「リファレンス」として公式ドキュメントを併せて参照するのは有用です。

e.g. ブログ記事でインストール方法が紹介されていた時に、公式ドキュメントではどういう方法でインストールを推奨してるかを合わせて参照する
- → 推奨されてるインストール方法が一番ユーザーが多い方法なので、問題が起きた時に問題が解決しやすい
e.g. ブログ記事でAPIの使い方が紹介されていた時に、公式ドキュメントではどういう用途で使うべきかが書かれているので合わせて参照する
- → 動きはするが公式ドキュメントでは非推奨だったり、代替手段が提供されてることに気付ける

上から全部読んで理解できるものになってるドキュメントは、かなり力入れて作られてるドキュメントです。そういうのは有名な {product} に多いですが、そうじゃない場合は無理に上から読む必要性はないと思います。 (有名であってもドキュメントを改善するリソースが足りないことはよくあるので、ドキュメントを改善するのは喜ばれる)

{product} の概要を知りたい

Getting Started や Examples で雰囲気がわかる
興味が出たら Tutorial などを触ってみる

ライブラリの作成者もドキュメントを書くのが上手ではない場合があるので、検索してわかりやすい説明がされてる記事なども合わせて参照するのがよさそう。

{product} が既存のものとは何が違うのか知りたい

Concepts を参照すると作成したモチベーションが書かれてることが多いので、ここで既存との違いを紹介されてることが多い
- 直接的に Compare 的な比較のセクションを設けてるものもある

e.g.

📝 公式ドキュメントに書かれていても、機能の比較テーブルは主張に過ぎないケースは多い。そのため、第三者による比較やベンチマークといった定量的に比較できるケースも合わせて参照する必要がある。

{product} の使い方が知りたい

TutorialとExampleを見る
変に難しいと思ったら、別のを探してみる
他ので理解できたら、Tutorialに戻ってみる

ドキュメントの設計として、TutorialはTutorialとして必要最小限のことを書いているタイプと Tutorialに全ての要素を詰め込んでしまって難しくなるタイプがあると思います。

前者は読みやすいと思います。一方で、後者は読むのが難しくなりやすいです。別の簡単なものがあるなら、まずはそれを一度見てから、なんとなくわかってきてから戻ってきた方が良いのかもしれません。

{product} の特定のAPIやコマンドの使い方が知りたい

API Reference を参照する
リポジトリで、APIを検索する
- テストコードもサンプルコードになる
- Issueで同じような問題にはまっている人が見つかるかしれない
GoogleやGitHubなどでAPIで検索する

{product} の動作原理が知りたい

ある機能がどう動いてるのかわからない場合

Examples からその機能のサンプルをとってくる
- 大体はメンテナンス性のために最小のコードになってるので、最小のコードで動かしながら試せる
- 公式のExamplesは大体メンテナンスされているので最新のサンプルコードであることが多い

その他

ドキュメントの読み方を知りたい

ドキュメントを書いてみると、読み方もわかるような気がする。

公式ドキュメントも最初は次のような1枚に収まるような内容で、これが収まらなくなってきたりして分割されたドキュメントサイトになることが多い。

## Concepts

作ったモチベーション

## Installation

インストール方法

## Usage

基本的な使い方

## Examples

動かせるサンプルコード

## API Reference

APIの説明

## License

ライセンス表記

何かを作ってREADMEを書いてみると、この辺のことはこのセクションに書くだろう的な感覚が掴めるような気がする。 READMEの書き方は色々なリポジトリを真似たり、HOW TO WRITE READMEとかで検索してみるとある種のパターンみたいなものが見つかりそう。

翻訳されてほしくないところも翻訳される

translate="no"属性があると大体の翻訳ツールは、その要素の翻訳をスキップしてくれる。

翻訳ツール次第だが、別途翻訳されてほしくない要素に対してtranslate属性を当てると改善できることがある。 (Translate Web Pagesのようなページ上でインライン翻訳するタイプはこういうので改善できる。URLを読み込ませて翻訳するサービスなどはこういう割り込みができないため、技術文章には向いていない)

こういうUserScriptでサイトを書き換えたりする

UserScript

// ==UserScript==
// @name        No Translate Element
// @namespace   https://github.com/azu
// @include     http://*
// @include     https://*
// @exclude     http://127.0.0.1:*
// @exclude     http://localhost:*
// @grant       none
// @version     1.0
// @author      azu
// @description Add no translate
// ==/UserScript==

const SKIP_BODY_MODIFY = ["https://github.com"];
const isGitHub = location.origin === "https://github.com"
function notranslate (){
  const origin = location.origin;
  // title
  const title = document.querySelector("title");
  if (title) {
    title.setAttribute("translate", "no");
  }
  if(isGitHub){
    Array.from(document.querySelectorAll(`#files, file-tree`), pre => {
      pre.classList.add("notranslate");
    });
  }
  if(SKIP_BODY_MODIFY.includes(origin)){
    return;
  }
  // pre tag
  Array.from(document.querySelectorAll("pre > code"), pre => {
    pre.classList.add("notranslate");
  });
  // pre[lang]
  Array.from(document.querySelectorAll(`pre[class*="lang"], pre[data-type="programlisting"], .monaco-editor, iframe, div.highlight > pre, .highlight, pre[class*="calibre"], pre.programlisting, pre[data-type="programlisting"], .source-code, #movie_player, [id^="docs-internal-guid-"] table`), pre => {
    pre.classList.add("notranslate");
  });
  // remove translate=no from html
  document.documentElement.removeAttribute("translate");
}
// Observe
const observer______ = new MutationObserver((mutations) => {
  window.requestIdleCallback(() => notranslate());
});
observer______.observe(document.body, { childList: true });
requestAnimationFrame(() => notranslate());
setInterval(() => notranslate(), 1000);

azu/README.md