なぜ僕は公式ドキュメントを読むのが苦手なのか

はじめに

皆さんは、『公式ドキュメントを読んだほうがいいよ』とよく耳にしませんか？

そこで、『よし読むぞ！』と思っても、なかなかうまくいきませんよね💦
（そういう方々がこの記事を見に来てくれると思っている👀）

私も、公式ドキュメントを読むのが苦手で、まず最初に、Qiitaなどの技術系ブログに頼ってしまいますw

そこで、なぜ自分が公式ドキュメントに苦手意識があり、どうしたらその抵抗をなくせるのかを考えたので、記録として記事にしたいと思います！🙆

ちなみに、公式ドキュメントとの思い出は、1年前ぐらいにDockerの公式ドキュメントで何が書いてあるか理解できず、15分くらいで読むことを諦めましたw

※自分がこの記事を通して公式ドキュメントが読めるようになるために努力した記事なので、公式ドキュメントを批判した記事ではないです！

対象読者

公式ドキュメントを読むのが苦手な若手エンジニア

😅公式ドキュメントがなぜ読めないのか

自分が公式ドキュメントを読めない理由を考えてみました。

以下が、自分が読めないと思う理由です。

• 知りたいことに対して、前提条件から読まないと理解できない
• 公式ドキュメントで情報をキャッチアップする意味を感じない
• 専門用語＋英語で書かれているので、翻訳しても何が書いてあるかわからない

以下で、一つずつその理由を書いていこうと思います。

😭知りたいことに対して、前提条件から読まないと理解できない

一番はこれかもしれないです。

自分みたいな若手エンジニアはわからないことが大半です。

専門的な用語はいまでもわからないことがありますし、そのわからないことが1つでもあるととても気になり、調べたくなります。（完璧に理解したいから）

例えば、わからないことがあったとして、その解決をしたいと思い、公式ドキュメントを読んでいるとします。

そこで、知りたいことと少しズレた内容の別のわからない単語が出て来たら、すぐ回答を得たいという気持ちから、別のタブを開きその単語をググることが多いです。

その作業を繰り返しているうちに、気づいたら本質にたどり着くまでに30分かかることもありますし、そもそも違うことにをしているときだってあります。w

情報を仕入れる時に、楽して早くキャッチアップしたいですよね。

そのため、これが公式ドキュメントを避ける原因かもしれません。

😭公式ドキュメントで情報をキャッチアップする意味を感じない

技術について大枠をキャッチアップしたいという目的に、公式ドキュメントを読み情報をキャッチアップする意味があると思います。

しかし、それ以降であれば、目的はバグを修正することやエラー解決が多く、そのために問題への逆引きが難しい公式ドキュメントを読もうとはならないですよね。

QiitaやZenn、他の開発者さんのブログの方が情報は、公式ドキュメントより噛み砕いて書いてあるので、楽して探せそうな気がします！

そのため、二次情報に頼りたいと思ってしまうのだと思います。

😭専門用語＋英語で書かれているので、翻訳しても何が書いてあるかわからない

英語が読めないという理由で公式ドキュメントを避けることはあまりなかったのですが、（翻訳があるので）

日本語翻訳した時に、「これなんのこと言ってるんだろう？」と思ったり

専門用語と英語が組み合わさると、公式ドキュメントの理解はさらに難しくなります。

特に、翻訳が正確でない場合もありますし、専門用語のニュアンスが失われる場合もあり、内容が入ってこない経験が多くあります。

また、コードの部分も自動で翻訳変換されてしまい読む側としては気持ち悪いのも公式ドキュメントを避けている理由です。

🙆‍♂️公式ドキュメントのいいところ

まず「なんで、公式ドキュメントを読めと言われるのか？」考えてみました。

• 信頼性が高い
  開発者自身が書いた内容であるため、情報の正確さが高いです。（1次リソースなので、当然の話かなと）
  いわゆる説明書みたいなものだと思っている。

• 必ず動くコードが得られる
  ここもいいところかなと思います。公式ドキュメント以外のリソースは、コードが記載されているが動かないということが多くある。

気づき

ここまで、自分が公式ドキュメントが苦手な理由と公式ドキュメントのいいところを知った時点で、

「公式ドキュメントは、読んで体系的な知識をつける」

つまり、エンジニアとして手数を増やす用途で使う記事（資料）な気がしてきました。

公式ドキュメントでは、体系的な知識をつけ、いざその言語やライブラリを使える場面になったときに、その機能の部分を、公式ドキュメントを見返したり、その他のテックブログで詳しく調べて使えばいいと感じました。

また、ライブラリ特有のエラーなどは公式ドキュメント詳しく読んだ方がいいとは思います！🙆‍♂️

とはいえ、自分の得意領域を一つ決めて、そこに対して精通するために公式ドキュメントを読破するのもありだと思います！

始めにQiitaやZenn、他の開発者さんのブログから知識をつけて、土台が固まったきたら公式ドキュメントを読むのもいいかもですね〜！

しかし、その技術を得意としようとしているのに、信頼性が高い公式ドキュメントを一度も目を通さないのはあまり良くない気はします！

💪公式ドキュメントが読めるようになるように努力してみた

これまで、屁理屈じみた公式ドキュメントを読めない理由を書きましたが、

エンジニアとしてステップアップをするには、公式ドキュメントからキャッチアップができたら良いと考えているので、公式ドキュメントを読めるようになるために努力してみました〜

🚀公式ドキュメントの各セクションの理解

まずは、相手を知るとこから、、、

公式ドキュメントやライブラリの使い方を理解する際に、異なるセクションがどのような目的で存在しているかを理解するとよみやすくなるかも、ということで

Getting Started:
これは、ライブラリをすぐに使い始めたい人向けのセクション。
インストールなど基本的なセットアップ手順が説明されています。

Quick Start | Echo

Tutorial:
ライブラリに慣れるための具体的な手順を提供しているのセクション。
このセクションを終えて、Getting Startedに戻って実際にアプリケーションで実践するのがよきです。

A Tour of Go

Concepts:
読むことがメインのセクション。概念を解説しています。
ここらへんで、こころが折れるw

Kubernatesの公式ドキュメント コンセプト

Examples:
コード例が提供されるセクション。
Getting Startedに戻って実際にアプリケーションで実践しようとなった時に、次ぐらいで見てるかもしれない。とりあえずコードを見よう的なノリ
多くの場合、ほぼそのまま実行できるかつ、うまく動かない時手元のコードと、Examplesと比較することが多いかも。

CRUD | Echo

API Reference:
APIの詳細を記載したセクション。
APIを使う時は、ここを見てる。
いっぱい書いてあり、無限スクロールに感じるw

accounts_changed eventAPI event

🚀少しやってみた

公式ドキュメントについて表面上は知れたと言うことで、次は中身ですね

公式ドキュメントで体系的な知識と仕様をキャッチアップできるように、頑張ってみました！

今回読んだのは、Goのフレームワーク echoの公式ドキュメントです！（例です）

ゴールは、簡単なTodoアプリのAPI（CRUD）を作ることです！

ちなみに、Go自体の経験はありますが、Ginしか触ったことなくて、手っ取り早くechoを触ろうと思います！

とりあえず、Quick Startから見ていって...

長くなるので、割愛させてもらいますwww🙇‍♂️🙇‍♂️🙇‍♂️

実際書いたコード

https://echo.labstack.com/docs/cookbook/crud

これをみながら、変えてみた🙆

package main

import (
	"net/http"
	"strconv"
	"sync"

	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
)

type (
	todo struct {
		ID     int    `json:"id"`
		Task   string `json:"task"`
		Status string `json:"status"`
	}
)

var (
	todos = map[int]*todo{}
	seq   = 1
	lock  = sync.Mutex{}
)

//----------
// Handlers
//----------

func createTodo(c echo.Context) error {
	lock.Lock()
	defer lock.Unlock()
	t := &todo{
		ID: seq,
	}
	if err := c.Bind(t); err != nil {
		return err
	}
	todos[t.ID] = t
	seq++
	return c.JSON(http.StatusCreated, t)
}

func getTodo(c echo.Context) error {
	lock.Lock()
	defer lock.Unlock()
	id, _ := strconv.Atoi(c.Param("id"))
	return c.JSON(http.StatusOK, todos[id])
}

func updateTodo(c echo.Context) error {
	lock.Lock()
	defer lock.Unlock()
	t := new(todo)
	if err := c.Bind(t); err != nil {
		return err
	}
	id, _ := strconv.Atoi(c.Param("id"))
	todos[id].Task = t.Task
	todos[id].Status = t.Status
	return c.JSON(http.StatusOK, todos[id])
}

func deleteTodo(c echo.Context) error {
	lock.Lock()
	defer lock.Unlock()
	id, _ := strconv.Atoi(c.Param("id"))
	delete(todos, id)
	return c.NoContent(http.StatusNoContent)
}

func getAllTodos(c echo.Context) error {
	lock.Lock()
	defer lock.Unlock()
	return c.JSON(http.StatusOK, todos)
}

func main() {
	e := echo.New()

	e.Use(middleware.Logger())
	e.Use(middleware.Recover())

	e.GET("/todos", getAllTodos)
	e.POST("/todos", createTodo)
	e.GET("/todos/:id", getTodo)
	e.PUT("/todos/:id", updateTodo)
	e.DELETE("/todos/:id", deleteTodo)

	e.Logger.Fatal(e.Start(":1323"))
}

$ curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"Task":"Study","Status":"WIP"}' \
  http://localhost:1323/todos

{"id":1,"task":"Study","status":"WIP"}

$ curl localhost:1323/todos/1

{"id":1,"task":"Study","status":"WIP"}

$ curl localhost:1323/todos

{"1":{"id":1,"task":"read book","status":"Done"}}

$ curl -X PUT \
  -H 'Content-Type: application/json' \
  -d '{"Task":"read book","Status":"Done"}' \
  http://localhost:1323/todos/1

{"id":1,"task":"read book","status":"Done"}

$ curl -X DELETE localhost:1323/todos/1

実際、公式ドキュメントを読みながら簡単に体系的な知識で動くコードが書けました！

公式ドキュメントがこんな時役立つ編を別記事で書こうかなとおもっています！

🚀Cursorでおしえてもらうことができる？

本質とは、ズレますが、公式ドキュメントを与えて開発できるらしい

おわりに

やや自己満な記事になってしまいましたが、公式ドキュメントを読めるようになるために、記事を通して頑張ってみました。

用途を考えれば、少しは好きになれそうで、またいいドキュメントだなと思いました。👏

公式ドキュメントは、言語仕様などの体系的な知識をつける目的やエンジニアとして手数を増やす目的なものであり、

いざその言語やライブラリを使う場面になったときに、その機能の部分の公式ドキュメントを見返したり、その他のテックブログで実際の使用例を詳しく調べて使えばいいと感じました。

公式ドキュメントが苦手なエンジニアですが、今後も、公式ドキュメントと仲良くできるように精進していきます！💪

参考

PR

HRBrainでは一緒に働いてくれる仲間を募集しています！😁