技術的なことをブログに書くときに気をつけていること

技術的なことをブログに書くこと

　私はよく技術的なことをブログに書いています。技術的なこととは何ぞやという話もあるかとは思いますが、今回の主題ではないので「プログラムのソースコードや、ハードウェアの回路図が出てくる記事」くらいのふんわりした定義とさせて下さい。

　今回は、それらの技術的な記事を書くときに私が気をつけていることを、自戒をこめて書いてみようかなと思います。一応書いておきますが「こういう書き方が素晴らしい！」とか「こう書くべきだ！」というわけではなくて「自分はこう書いています」という表明というか、ただのメモみたいなものです。「こういうのも書くとよいかも！」といった優しいコメントを期待しています。

　どうかけば良いのか分からないので、適当に5W+1Hの観点で書いていこうかなと思います。

何故技術的なことをブログに書くか（Why）

　そもそも何故書くのかという哲学的（？）な問いがあります。私の場合は完全に自分のメモです。多分私のブログを一番参考にしているのは私自身だと思います。結構同じことやることって、多いのですが、記憶力が絶望的に無いので、同じところでつまづいて時間をとられることが多いので、必ずメモをするようにしています。

　今時は検索しても、今は色々情報は出てくるのですが、書いている人と自分のレベルが違いすぎたりすると、つまづく所が違ってあんまり参考にならなかったりするんですよね。なので、自分のメモが最強かなと個人的には思っています。

　実際、Raspberry Piとか何度もセットアップしていますけど、必ず自分の下記記事を参考にしながらインストールしています。

　こうすると、うまくいかなかったとき自分が間違っているのか、他の何かが変わったのかも判断しやすいので助かるんですよね。

　同じような記事がネットにたくさんあることは、賛否両論あるかもしれませんが私は賛成派です（もちろんパクリはダメですが）、自分の理解の助けにもなりますし、何よりバックアップにもなります。参考にしていた記事が無くなってしまったり、何らかの古い情報が知りたいのに大きく書き換わってしまっていたことに絶望した経験のある人は多いでしょう。他人を信じてはいけません、自分で守るのです。

　あと、お金のためには書かない方が良いかなと個人的には思います。技術的な記事って真面目にかくと、恐ろしいほど効率が悪いので。他のことにモチベーションを見出さないと続けられないかなと思います。

誰のためのブログを書くか（Who）

　上記で書いたように、自分で自分のためにブログを書いています。個人のメモ帳に書かずにWebに公開するのは「自分で検索しやすいから」くらいの理由だったりします。

　一応多少は、レベルが異なる人でも理解できるように気を使うようにはしていますが、全くのパソコン初心者と数十年ソフト開発をしているような人では書き方は全然変わってきてしまうので、ある程度で諦めています。

　1万人に1人くらいが参考にしてくれたら良いな、くらいの気持ちで書いています。

どこに/どこで書くべきか（Where）

　書く場所（コンテンツを書き留める場所の意味）はどこでも良いかなと思っていますが、一箇所にまとめる方が検索がしやすいので良いかなと思っています。

　私は、はてなブログで書いています。日記とか、写真の記事とかとごちゃ混ぜに書いています。なので、写真日記の直後にTensorFlowでディープラーニングのソフト実装する記事があるとか、結構カオスなことになっていますが、自分はあんまり気にしていません。ブログなんて深く考えず好きなこと書けば良いと思っています（お金が目的なら別）。

　あとは、GitHub Pagesを活用するのもよいかなと思います。

　Qiitaも悪くないと思います。ただ、私はあんまり書く気にはなれないですが（個人的な好みです）。

　書く場所（自分がブログを書いているときにいる場所の意味）は、基本的に家で書いています。コピペとか画像が多いこともありますが、モバイルでも、ブログ書こうと挑戦したことあるのですが、大きいキーボードでないと極端に入力遅くなってしまうのでダメでした。そのうち再チャレンジしたいところです。

何を書くか（What）

環境・バージョン情報

　環境やバージョン情報は、なるべく詳しく書いた方が良いです（と言う私もあんまりできてないですが）。とりあえずMac, Windows, LinuxのどのOSを想定しているのかくらいは書いた方が良いかなと思います（わかる人はわかるのですが、わからない人にはちょっと不親切かなと思います）。

　あと、使用しているライブラリやライブラリのバージョンもかいておくとなおGoodです。バージョンアップで後方互換がなくなりやすいもの、例えば機械学習系（ディープラーニング）は特に注意しましょう。Chainerとかバージョン変わると全然動かないですからね。

　pythonだと、以下コマンドで使用しているパッケージとバージョンを一気に書き出せるので便利です（最近知りました）。多分他の言語でも似たような機能あるはずなので、調べてみると便利です。

$ pip freeze > requirements.txt

その技術がどういう役に立つか

　これは個人的な好みなのですが、なるべくその技術で何ができるのかというアプリケーションを書くようにしています。具体的には、単純にAmazon Dashボタンを単にハックするだけじゃなくて、ルンバを動かしたり、家庭菜園の撮影に使ったりとか、マルコフ連鎖で文章自動生成するだけでなく、ブログに記事投稿してみるとか。

　単にメモだけでも良いのですが、技術というのは、何かの役に立ってナンボなところもあるので、なるべく応用例を示したいなという気持ちはあります。自分の生活に役立つと思うと、興味を持ってくれる人が少しは増えているのじゃないかなという、わずかばかりのサービス精神もあります。

ソースコード・ライセンス

　基本的にはソースコードは、ほぼ全てGitHubで公開しています。仕事じゃないですし、隠すほどのものでもないので。自分はクソみたいなコードさらすことに全然抵抗ないので、ガンガンネットにアップロードしています。気に入らない人は、口出す暇があるなら、自分がお手本見せるかPull Request投げればよいのです。

　GitHubのアカウントは以下です。PR待ってます！

　あと、ライセンスも表記するようにしています。真面目な人ほど、ライセンス無いソフトウェアの流用をためらうので、もし多くの人に使ってもらうことに問題がないのであれば、MITライセンスとかのゆるいライセンスで公開すると、多くの人を幸せにできるかもしれません。

いつ書くか（When）

　好きなときに書くのが良いかなと思います。

　あと、新しい情報書くときは、古いのを消さないほうが良いかなと個人的には思います。昔の環境で動かさざるを得ないとき（意外にこういうことあったりします）に参考になる場合が出てくるので。そういう場合は、新しい記事を書くと共に、古い記事から「こちらが最新の情報です」といったリンクを貼るのが良いのかなと思っています。スマートじゃない気もしますが、こういったアナログ（？）な方法が一番手軽でわかりやすいかなと思っています。

どうやって書くか（How）

　ソースコードを書くなら、Markdown方式がオススメです。GitHubとかでも使えますしね。ソースコードとか、以下のように色分けして区別して表示できると、ちょっと見やすい気もしますよね。

print ("hello unko")

　Markdownは、主要なものくらいなら1日で多少は使えるようになると思いますので、1度チャレンジしてみるとよいかと思います。早速はてな記法から乗り換えようかな！という人は以下記事参照ください。

書かないこと

　最後に書かないことに関してです。基本的には、犯罪行為で無ければ何でも書いて良いと思っているのですが、唯一気にしているのは本業の業務内に得た知識は書かないということでしょうか。コンサバな会社なので、ブログ書くことは禁止も推奨もされていない（無関心）ので、万が一何か言われたら面倒なので。

　なので、このブログの技術的っぽく見えることは、ほとんど素人がやっていることなので注意して下さいね！（今更感）。逆にブログの内容を本業に活かすことはあってもよいかなと思っています（現状はほとんど無いですが）。あんまり仕事とブログの内容が近くなってくると線引きが難しくなってくるので、そしらたら、ブログの内容をだんだん本業とずらしていけば良いかなと思っています。

まとめ

　だらだらと取り留めの無いことを書いてしまいました。繰り返しになりますが、あくまで自分が気をつけている（気をつけたい）ということです。私もこれらを毎回できているかというと、そうでもないわけで、自戒も込めて書いてみました。もし一つでも参考になる内容があれば幸いです。技術的なことを書くブログ（特にソフト以外のエレキ、メカ関係）がもっと増えるとうれしいなと思います。

参考リンク

http://www.daipanman.com/entry/2017/09/14/162232

私の技術記事の書き方 - azukiazusaのブログ