難しい漢字を使わない

パソコンで打つと簡単に漢字に変換できてしまうのですが、それが仇となって難しい漢字を使いがちです。
よく見るものだと「所謂」があります。いわゆると読みます。私は最初読めませんでした。

技術解説は特に、細かいところに思わぬ注意点があったりして、一字一句ちゃんと読まないといけないのですが、所々に読めない漢字が含まれていると読む気を失ってしまいます。

自分が読めない・書けない・書いたことがないような感じは平仮名にする

無駄なコードを書かない

私もうっかりしているとよくやってしまうのですが、本当に伝えたいコード以外のコードが多くて、何が言いたいのか分からないパターンです。

「〜の使い方」系の解説でよく見かけます。

例えばRubyのreverseメソッド(文字列を反転させる)の使い方を解説するような以下のコード

firstname, lastname = gets.split(" ")
fullname = firstname + lastname
if fullname.size > 20
  puts fullname.reverse
else
  puts fullname
end

reverseの使い方だけなら

"abcdef".reverse

だけでいいのに、標準入力を受け取るgetsや文字列を分割するsplitなど、余計なコードが多いです。
これは大袈裟な例かと思いきや、そんなことはなくて、これに近い解説は結構あります。

余計なものは省いて、シンプルな例にする

こまめに実行

比較的短いコードだと問題ないのですが、RailsやLaravelのように、複数のファイルを触るような解説では、できるだけこまめに実行していった方がいいです。

実際にあった教材なのですが、Rails・Laravelでindexからnew,create,edit,update,destroyの処理をコントローラ・ビュー合わせて全部書かせてから、初めて実行させるというものがありました。

これだと、もしエラーが出た場合に、初心者にはどこが問題なのか見当もつきませんし、どのコードがどのように作用しているのかも分かりにくいです。

indexのアクション、ビューを書いたら実行・動作確認、次のアクションを書いたら実行・動作確認というように、こまめに実行させ、結果を確認してもらうことで、間違った場所やコードの意味が分かりやすくなります。

２０行ぐらいのコードであっても、少しずつそのプログラムが出来上がっていく工程を書くことで、どのようにプログラムが出来上がっていくのか伝わりやすくなります。

できるだけ小さくまとまった単位で実行する

動くサンプルコード

ちゃんと動くサンプルコードを書きましょう。

手元で動作確認しても、コードエディターから文書へ写すタイミングでタイプミスなどは起こりえます。
私がいつもやっているのは、文書のコードをコピーしてきて、エディターへペーストし、実行できるかチェックします。

このようにチェックしても、文書中のコードを少し修正するときは、少しの修正だからと油断しがちです。
あるいは、コード中にコメントアウトを残す場合も注意が必要です。

技術解説を書くような人の多くは、複数の言語を触っていると思うのですが、言語ごとにコメントアウトの書き方が異なるため、間違ってRubyのコードにcssのコメント書いてしまう場合もあります。
コードエディタだとちゃんと教えてくれるのですが、文書用のエディタとなると、気づかないまま公開してしまいます。

コードは毎回動作確認する

hoge,fugaを使わない

何の躊躇もなくhogeやfugaを使ってしまいますが、初めてhogeやfugaを見る人は特別な命令か何かだと勘違いしてしまいます。
「hogeとはなんですか？」これ結構プログラミング初心者の方から質問されます。

hogeやfugaを使うタイミングとしては、具体例を書くときだと思うのですが、具体例なのですから、実際に実務などで使ったモデルや変数名を使った方がリアルで、コードの「使い所」が分かりやすくなります。

名前大事

動機を書く

ラスト２つに最も言いたかったことを持ってきてしまいました。
技術書において最も大切なのは、「動機」です。
「〜使い方」系は読む側も動機がはっきりしている(使いたい)と思うので、別に書かなくてもいいですが、フレームワークやツールの概要を解説するときは、必ず書いた方がいいです。

特に解説が長くなってしまうものほど、動機が書かれていないと、「長いからいいや」と思われてしまいます。
私はdockerというものに度々興味を持ち、その度に調べてみるのですが、「dockerはコンテナがどうのこうの」「素早く立ち上がる〜なんとか〜」みたいに書かれていても、「Macで開発できてるからいいや」と思ってしまいます。

解説を書くぐらいの人であれば、そのツールやフレームワークを使う理由が必ずあるはずです。これを使うとこんなにいいことがある、xxで困っていたけど、これを使ったら解決した。みたいに、なぜ自分たちが使っているのかを語ってもらえると、「じゃあ長いけど必要そうだからちゃんと読んでみよう！」と思ってもらえるはずです。

信者を増やす

推論可能な例えを書く

「オブジェクト指向のクラスは車に例えられて、車輪がなんとかで〜」

みたいな例え、全く無意味です。車に詳しくなるだけです。こういう例えで「理解できた！」って言ってる人で、実際にコードが書けるようになった人みたことないです。

「例え」について正しく理解して欲しいのですが、例えって、静的なものではなく動的なものです。
つまり、例えて終わりじゃなくて、「例え->推論->戻ってくる」ができないとダメです。
クラスを何かに例えたのであれば、最終的な目的はクラスを理解することです。例えを理解することではありません。
例えを通して、難しい概念を理解することが真の目的です。

真の目的を忘れない