読み手をイライラさせない技術記事などを書くために最低限守ったほうがいいこと

追記: この記事は「人が一生懸命書いた記事を読んでイライラする人間」を擁護するつもりは一切ありません。

追記: この記事は「自分の記事ではイライラさせたくないな」と思う人向けに執筆したのであって、この記事のあることをQiitaにあるすべての記事に矯正したいという思想のもとで執筆したものでは有りません。

はじめに

こんにちは

Qiitaやnoteといった情報共有に向いたサービスがどんどん普及しており、知識量に関係なく誰でも情報が発信できるいい時代になりましたね。

しかし、投稿されているすべての記事が良いと思えるわけではないのは確かです。タイトルに書いてあるものとは違う内容が書いてあったり、問題解決まで達していない結論で終わってたり。記事中の動かないコードを調べるために、そこから別の記事をはしごをして、それを繰り返していた結果業務時間が終わっていたり。

あまり私も人のことは言えませんが、いろんな記事が増えるにつれて、こういった見てる方を疲れさせる記事や、リンクを踏んだことを後悔させてしまう記事が非常に多くなっているのは確かだと思います。しかし、かという私達もこのような記事を書いてしまう可能性は十分にあります。

そこで、今回は私が普段考えている技術記事を書くときに、最低限守るべきと考えていることをチェックリストにしてまとめてみました。これは、私自身の記事を見返したときや他の方の記事を見たときに、疑問に思ったこと・違和感を持ったことを元に作っています。

私がこれらのことを心に留めながら記事を書くと、他人のチェックや投稿後での指摘がだいぶ少なくなりました。皆さんにも是非役に立ってもらえれば嬉しいです。

また、なぜそのチェックリストにその項目があるかの解説も、続きに書いています。これも見ておいてください。全部鵜呑みにするのは構いませんが、このチェックリストが正しいという確証はないです。ちゃんと解説読んで自分で解釈して、納得できるかを考えましょう。

このチェックリストが役立つ場面

なにか技術に関するドキュメント・記事を書く際にこのチェックリストが役に立つと思います。例えば、私はQiitaの技術記事やカンファレンスのトークへのプロポーザルを書くときに実践するように心がけています。

多分読んでたらわかると思いますが、このチェックリストは

• 主に特定の問題への解決法を書いたもの、Tips集といった技術記事 [^tech article]
• ストーリー性のあるような技術記事（トークのプロポーザル等も含む）¹
• 技術ポエム (この記事みたいなやつ)

これらの３パターンの観点があると考えると、それぞれ守るべきこと・あまり守らなくていいことがあると思います。そこも吟味しながら、解説をさっと見てもらえると幸いです。

あと、解説中では、主にプロポーザルとかポエムなどの「書きもの」はまとめて「記事」という単語でまとめられていることがあります。

対象者

ある程度、執筆によるアウトプットの習慣がついてきたかな？と思っている人。
アウトプット始めたての人は、あまり意識しすぎて気軽に記事が書けないようになるのも良くないので、サラッと見て「こういう考えがあるんだな」と思うくらいにしておいた方が良いと思います。

おおまかなチェックリスト

• 「全体の構成」的な観点

  • タイトルと書いている内容が矛盾してないか
  • 問題提起と提案は紐付いているか
  • 文章構成はしっかりとしているのか

• 「細かいところ」的な観点

  • バージョンなどの環境の情報はできる限り書いているか
  • 動かないコードを書いてないか
  • 情報源は書いているか
  • 注釈は無視できるか

各チェックリストの解説

タイトルと書いている内容が矛盾してないか

タイトルと書いている内容が矛盾しているものは、あまり良いものではないです。タイトルで知りたいことを知ろうとして、最後まで読んだ人の時間を奪っていることになりうると思います。たぶん、これはなかなかやらかさないと思います。

一時期よく見た悪い例は、タイトルにも書いてないのに「できませんでした」とだけ終わっている記事です。これは読んでいる人の時間を無駄にすることが多いと思います。それに、発言力のある人に見つかれば、最悪SNSにさらされて炎上するので、書いた人にもいいことはありません。

なかなか無いですが、別のサイトへのリンクを張っただけで終わる記事も論外です。参考文献でもなくリダイレクトの意味でリンクを張ったものとかは、「記事がBlogに移行した」「日本語にチョット訳した（これも翻訳権が行使される場面では、ちゃんと許可とってくださいね）」等の正当な理由のない限り、やめましょう。

文章構成はしっかりとしているのか

ストーリー性のある記事を書くのなら、導入や説明、まとめの文章構成の流れはしっかりしましょう。まとめや説明がぐちゃぐちゃになっていたり、どれか一つが欠けても通じる文章は、よっぽどな文才にしか書け無いと思います。

確証はないですが、個人的には構成がしっかりしている文章は一番読みやすい、と考えています。なぜなら

• タイトル、冒頭などの文章の最初の段階で、頭の中でその記事が何が伝えたいのか・何をやりたいのかを理解し、
• それを踏まえ、その後の詳しい説明の内容を読みながら、 それまでに出てきた情報整理し、
• そして 「まとめ」にあたる 内容をみて、今までの情報から自分が考えるべき内容を吟味する

こういった事が文章の構造がしっかりしていると、楽にできるからです。次の「問題提起と提案は紐付いているか」と合わせてみると、論理的に書く、ということと似てると私は考えています。

問題提起と提案は紐付いているか

これはトークのプロポーザルなどにも当てはまりますが、その記事の中で何が問題になっているか、そしてちゃんとそれが提案と十分にマッチしているのかは大事です。

私が見た中でうーんと思ったのは、「XXXというライブラリでYYYができない問題の解決法」のようなタイトルの記事で「XXXを捨ててZZZを利用しよう」という提案をしていたものです。私は、XXXをフルで利用してコードを書いていましたが、これは「XXXは時代遅れ、ZZZにしよう」と、ZZZへのフルスクラッチを結論で勧めているような記事でした。問題提起と提案がセットになった記事でそれを書くのは、少々ズレていると感じました。

また、リストの「タイトルと書いている内容が矛盾してないか」にもある通り、ZZZの提案をするなら、最初から記事のタイトルに「XXXというライブラリではYYYができないのでZZZを使おう」と書けばいいのでは、と思いました。

書いている人には問題と提案がマッチしているように見えても、傍から見ると全然マッチしていない・わかりにくい、ということもよくあります。ある程度文章を書いてみたら、客観的に問題提起と提案がマッチしているかを自分でレビューしましょう。

ただ、提案の内容は読者のコンテキストにもかなり寄ると思います。ZZZへのフルスクラッチも許容できるかも知れません。読者のコンテキストが定まるなら、できるだけそれに寄せた提案をしたほうがいいでしょう。[^ipod touch]

バージョンなどの環境の情報はできる限り書いているか

その記事の書いてある内容に関して検証した際のライブラリのバージョンなどの環境は、できるだけ書いたほうがいいです。

１、２年後であれ、その書いた記事は検索に引っかかり、いつか誰かの目に留まると思います。そのときには、書いてあるコードのライブラリのバージョンもアップデートされ、関数の名前や作用が変わったり、 deprecated(非推奨) になっているかもしれません。

誰かが昔の記事を見つけて、記事にあるコードをいろいろ試して、さて動かなかった。いろいろまた検索してみたけど、（バージョンの古いコードなので）なかなか多く出てこない。...(長時間の検索エンジンとの格闘) ...あ、バージョンの問題でした。ってなったらイライラするポイントになると思います。それだけではなく、動くけど deprecated(非推奨) なものをそのまま読ませたら、それが負債になったりますよね。

バージョン関連の問題ということは、勘がいい人は記事の日付などから分かると思います。しかし、全部の人がそうとは限りません。プログラミング初心者の方は特にそれが難しいと思います。

記事をより時間的にもユニバーサルな（通用するような）ものにするためには、バージョンの情報をしっかりと書きましょう。ある程度は助けになります。先程言った、勘がいい人もこのバージョン情報があれば、検証の糧になります。

例）
この記事は

python 3.7
tensorflow 1.17
opencv 3.6

を利用しています。

特に、多くライブラリが絡む記事のバージョンは気をつけたほうがいい

タイトルの通り、多くのライブラリが絡んでしまう内容は、バージョン表記には特に気をつけましょう。

個人的な体験を言えば、Python及びPythonのライブラリは特にそうだと思います。²

たくさん import しているソースコードは、当然ですがその分バージョンの依存があります。しかし、たとえ半数以上が動かなくなったとしても、一度コピペして動かさない限りはそれを知る事はできないです。また、一度の起動で一気に使えるか、そうでないかをすべて判別することはできないです。逐一起動してはエラーを修復して、、、、となるので、読み手にかなりの時間を要することとなります。

動かないコードを書いてないか

これは特に気をつけましょう。ある程度問題解決力がある人は、こういう問題は自分で解決できます。が、どちらにせよ、読んで試した人には少しヘイトが溜まります。全角/ 半角/ シンタックスエラー など様々な要因があります。

一度記事を書く前に、一つ深呼吸して、一旦全部の動作をチェックしてみるのはいかがでしょうか？

たとえ書き方が普通であっても、問題になりうることはたくさんあります。たとえばパスワードを環境変数に入れる際、プレースホルダーなどで表現するときには、

$ export PASSWORD=xxxxxxxxx-xxxxxxxxxxxx-xxxxxxxxxxxx

こういう風に書くと思います。しかし、このコードの前後で「これはプレースホルダーです」という旨はかんたんに書いておきましょう。プレースホルダーを含んだコードの行数が少ないのならばいいですが、多いコードとなると把握しにくくなります。

言うまでもないですが、シンタックスハイライトの機能は使いましょう。

情報源は書いているか

例えば、ある記事を参考にしたQiitaの記事を書いたとします。参考と一言に言っても、写経っぽくなったりするのはよくあります。それで、参考元の記事の筆者から「なんにも参考元として書かれてないけど、これパクリじゃない？」と言われ炎上寸前（もしくは炎上済み）になって記事を削除する、、、、、なんてこと、かれこれ数回見ました（そもそも、完全にコピーみたいな写経はアウトですが・・・）。

少しでも参考にしているなら情報源として記事の中でクレジットしましょう。多くの読み手は気づかないのでイライラしませんが、情報源を作った人からは不快な気持ちになります（それ以前に著作物に関するルールでアウトですが）。

注釈は無視できるか

注釈は基本的におまけだと、私は考えています。記事中のセクション中で言及すべき重要事項ならばそこに書きましょう。

例えば、ネットワーク系の問題を解決する記事の中で、載せているコードの副作用にセキュリティホールを発生させるものがあるならば、（知っていたら）それは注釈に書くべきではないです。でも、書いてしまう人がいます。

個人的には、注釈に入れられるのは次のリストに上げるものが主だと思います

• 単語の説明（わからないなら飛べばいいし、わかるなら飛ばなくていい、単語を知っている人なら特に重要じゃないやつ）
• 情報源・詳しい説明へのリンク（記事の本筋とかは関係ないので、注釈を無視しても大丈夫）
• 持論（技術の解説記事だと、まさに記事を読んでいる人にはどうでもいい。しかし懸念や、ポエムなど、コンテキストによる。書いている人の裁量にもよる）

もし、死にものぐるいで何かを急いで調べている人がいたら、急いで読んでいるので注釈を無視する可能性があるかもしれません。そういう人が無視しても大丈夫なことなら、それを注釈としてみるのもいいかも知れません。ただ、上の注釈にすべきリストの「持論」に書いたとおり、ここは書く人の裁量でいいと思います。

まとめ

と、ここまでリストについて解説しましたが、いかがでしたでしょうか？

これはあくまで最低限のリストなので、そもそも文章を書く上で守るべきことは次のリストにあるものなども、たくさんあると思います。

• 単語の統一
• 文のねじれの解消
• 文法ミス、Typoを潰す
• 嘘書かない、ちゃんと調べる etc ...

全部を守って完璧な記事を出すのは難しいですが、完璧にできるよう落ち着いて記事を何度も見返し、できる限りミスを取り除くのは大事です。急いで出したい気持ちもわかりますが、一回深呼吸して、もう一度文章を見てみてください。

また、記事に問題があると、読む人もそうですが、書く人も不幸になると思います。この人は、あまりよくわからない記事を書かない、嘘しか書かない、、、、みたいなレッテルを貼られるのは嫌ですよね。最悪の場合、炎上するとかも望んでいることではないです。

それらを早くから防止できるようにしてほしい、という願いもこのリストにはこもっているので是非活用してみてください。

皆さんの執筆・発信ライフがより良いものになることを祈っています。

[^ipod touch]: 昔、私が見た「iPod touchの電池の減りを軽減する方法」を解説するたくさんのサイトに「Wi-Fiを切る」という解決方法が提案されていることが多々ありました。その時の私の頭の中では「Wi-Fiを切るとiPod touchでブラウジングできないじゃん」という疑問点がありました。しかし、「iPod touchをただの音楽プレイヤー思っている」というコンテキストをもった人にとっては、違う話ですよね。このタイプ解説サイトは万人が見るので、どれかのコンテキストを定めることは難しいですし、どんな記事でもどこまで歩み寄るか難しいです。しかし、コンテキストが定まってたり他の記事との差を開きたいなら、ある程度はそのコンテキストに寄せるように考えたほうがいいでしょう

[^tech article]: https://qiita.com/freddi_/items/d734708878f8da5ecf4a とか

1. https://www.papercall.io/speakers/53728/speaker_talks/169558-deep-dive-into-optimizing-and-diagnostic-your-swift-code-swift とか、 https://engineering.linecorp.com/ja/blog/swift-compile-build-time/ とか ↩

2. 体感ですが、Tensorflowなどの機械学習系のライブラリは、数ヶ月というレベルで関数の名前が変わったりします。 ↩