2015-02-10

技術ブログを書いてくれてる人に申し上げたいこと6つ

はじめに

いつもお世話になってます! 助かってます! ありがとうございます! 解説サイトの人は特にありがとうございます

How to doは多いけど、Why I did in this wayで書かれてる記事が極端に少ないこと

たぶん備忘録として書いている人が多いと思うんだけど、

マニュアルのような書き方が多い気がします。

いやまあマニュアルがないよりは遥かに嬉しいことなんですが。重ね重ねいつもありがとうございます

『AしてBしてCすると、コレができる! かんたん!』で終わっていることが多いです。

多いというか、ほぼこれです。

ほげほげのためにA、もげもげのためにB、FUBARのためにCすると、コレができる』というように書いてくれると相当嬉しいです!

別に『これこれをクリックして…』とか『bashとはうんたらかんたら』とか詳細を書かなくてもいいので、こういう目的のためにやったと書いてくれると嬉しいです。

コマンド見ればわかるでしょ?』とお思いかもしれませんが、あなた必死に調べて公開したことにググってたどり着いた人が、そんなに技術力優れているわけないです。

はい技術力なくてすみません

『それを書かないとコレができない』とかじゃなくて、初見のものは、『な……な、なんでこういうコマンドを打つんだ……?』となったりします。

数学で解答見たら答えだけ書いてあるかんじで、なんでそうなるのかよくわかってない感じに近いです。

さらに、あなたがこれを書けば、なぜそうしたか明確にすることで他人から「あ、それはそういう意味で使われてるんじゃないよ」とレビューを受けることができるというメリットもあるはずです。

  • 追記(2015.02.10 19:03):

 これに関して批判がやや多いようなので追記させていただきます

 これをコードデザインとして捉えると、説明が極端に少ないということは1つのクラス記事)の中で匿名メソッド自分が実行したこと)ばかり使っているような感を受けます

 なぜこうしたか書くというのは、長々とコメント・解説を書いてほしいというものではなくて、

 自然言語ある意味手続き型重視のOOPのようなものですから

 1つ1つのメソッドに命名していくぐらいといったノリでやってほしいですと言いたかったのですが、言葉が足りなかったです(命名も難しいわけですが……)

 もっとも『見ればわかるでしょ』のように自分にとっては自明な物もありますし、書く労力の問題もありますので、さじ加減は難しいと思います

 それでも、可能な限りこれを意識して書いていただければ大変嬉しく思います

 本当は『そうすればお互い助かる』と言いたいのですが、僕が助けられることが少なすぎるので、申し訳ないです。

僕たちはみんなMacbashを使っているわけじゃないこと

特にMac記事に多い気がするのですが、Mac記事で、タイトルMacが入ってないことが結構あります

初心者のうちは『こちとらWindows使ってるわけじゃないのに唐突Windowsの話するな詐欺か』と言っていたことがありましたが、

最近ではMacについて言っています仮想マシンUbuntu入れたときにそういうことが何度かありました。

まあコマンドの詳細(例えば/Library/なんたらというパスを見かけると)を見れば『あ、これMacの話ね』とわかるのですが、

できればタイトルに『Macほげほげした』とかカテゴリなどに『Mac』と入れてほしいです。

これは他のOSなどでも同じです。

あと、「bashでこんなことができるよ!」なども、そのOSを明記した方がいいと思います

MacあくまDarwinなので、別のディストリビューションbashではできないこと・できることがあります

僕も普段はMac、たまにUbuntu、気が向いたときWindowsなので、別にMac向けの記事を開いたときでも「ありがとうございますありがとうございます!」となりますが、これを一般的な物っぽく断定されると、つらいです。

.bash_profileに書きなさいとかは、まあ僕zshなんすよぐへへとか思うだけであまり実害はない気がします。いまのところの僕は。

断定口調で間違ったこと言うのやめてほしいです

『これはこうするもの』と明確に言ってて実は間違ったことを書いている人がかなりかなり多いです。

バグだ!』系はかなりそれです。それバグじゃないです。

僕がブログ主さんよりも知識があればすぐに間違いに気付きますが、そうではない場合(そうではない場合が圧倒的に多い)、それに気付くのに時間がかかります

おかげで最近人間不信になっています

圧倒的自信がないのであれば、『〜らしい』『よくわからないけど〜』『こうしたら動いた』『ということだと思う』『〜するために、とりあえずこうしてみた』と書いていただけると、

「とりあえずこれは難しいんだな。失敗するかもしれないわけだな」という予測がついてとてつもなく助かります

コンパイル不可能ソースや実行不可能コマンドを載せないで……

これ本当に動いたのか……?と不安になります

今はGitHubからにょろ〜んしてくるのでそういうことはありませんが、初心者の頃はこれが頻発していました。

載せるときブログ上で書くのではなくて、コンパイルして通ったやつをコピペしてほしいです。

GistというGitHubに上げたソースを表示できるものもあります

情報源に関してはなるべく明記してくださるとありがたいです

これに関してはかなり多くの人が書いてくださっているので、今更言うまでもないことですが、たまにない場合もあります

参考にしたサイトを書いていただけると大変ありがたいです。

あなたにとってとても簡単であたりまえに解決したことは、全然簡単じゃなかったりしま

くだらないことでも書いてくださると嬉しいです。

中級者以上の方の『こんなの当たり前だからわざわざ書くまでもないよ』は、ほとんどの場合、初級者にとっては当たり前ではありません。ナニソレ初耳です。

さすがに中級者の人に、「if文とはほにゃららである」なんて解説を求めるようなことはしませんが、『別に書くまでもないこと』を書いていただきたいです。

世の中、初心者の人の方が人口が多いので、PVも増えてたぶんお得です。

おわりに

以上が初心者を抜け出したばかりの初級者の提案です。

批判もあるかと思いますが、できればすべて受け入れてくださると、僕と僕みたいに困ってる人が嬉しいと思います

ゲーム理論みたいですが、一人だけしかこれをやらなければ、『なんで俺ばっかこんなに詳しく書いてるんだ』となるかもしれませんが、

もしみんながこれをやれば、きっとプログラマ全体の生産性が上がるんじゃないかと思います

ぜひ、今日から僕が上記に挙げたこととVimを取り入れていただけると、非常に嬉しく思います

最後にもう一度申し上げますが、いつも技術ブログで助かってます

本当にありがとうございます

トラックバック - http://anond.hatelabo.jp/20150210030728
  • http://anond.hatelabo.jp/20150210030728

    相変わらずの唐突なVim

  • http://anond.hatelabo.jp/20150210030728

    How to doは多いけど、Why I did in this wayで書かれてる記事が極端に少ない これは技術ブログだけじゃなくて専門書全般に言えるよなー。天下り式に定理説明してるだけの大学の教科書多す...

  • http://anond.hatelabo.jp/20150210030728

    『ほげほげのためにA、もげもげのためにB、FUBARのためにCすると、コレができる』というように書いてくれると相当嬉しいです! これは恐らく、書いてる人のほとんどはそれを理解し...

    • http://anond.hatelabo.jp/20150210103855

      そもそも理解していない人が書いている、ってのもあるだろうし、 独自の見解を書いて批判が来るリスクを考えると書きにくい(だから権威あるソースからコピペしたような説明に終始...

      • http://anond.hatelabo.jp/20150210111338

        独自の見解を書いて批判が来るリスクを考えると書きにくい(だから権威あるソースからコピペしたような説明に終始する)ってのもあると思う。 それは無いと思うけどなあ。 俺はブ...

        • http://anond.hatelabo.jp/20150210115750

          「実際に批判が来るかどうか」はあまり関係なくて、そういうリスクを負いたくない、って思うかどうかの話だよ。 今回のテロでもまったく関係ないはずのアニメ番組で自粛が起きたよ...

          • http://anond.hatelabo.jp/20150210120102

            技術系の話すんのにそこまで臆病だってのは、もう適正が無いと言った方がいいんじゃないかって気がするな。 科学技術の世界からopen-minded communicationsを無くしたら存在意義かなり無く...

  • http://anond.hatelabo.jp/20150210030728

    mac使ってる奴はバカなんだから バカに期待するなよ あいつらMacしかしらねーからMacにあるやつはLinuxとかにもあるとkか本気で思ってるから

  • http://anond.hatelabo.jp/20150210030728

    あとね、新しいツールやライブラリや言語が出ると「ちょっと使ってみた系」の内容ほぼゼロの記事を書くの辞めて欲しい。 ググったときにそんなのばっかにあたって嫌になること多し...

  • http://anond.hatelabo.jp/20150210030728

    新手のクレクレですか?

  • http://anond.hatelabo.jp/20150210030728

    某技術ブログを書いている人です。 批判もあるかと思いますが、できればすべて受け入れてくださると、僕と僕みたいに困ってる人が嬉しいと思います。 気が向いたらでかまわない...

  • http://anond.hatelabo.jp/20150210030728

    いつもお世話になってます! 助かってます! ありがとうございます! 解説サイトの人は特にありがとうございます! 最後にもう一度申し上げますが、いつも技術系ブログで助...

  • http://anond.hatelabo.jp/20150210030728

    いやまあ、みんな暇があるわけでもなし。 詳しい部分は自分で調べて、blogにすると後進が助かるんじゃないかな。 自分の技術力も上がるし。

  • http://anond.hatelabo.jp/20150210030728

    元増田です。 大変素晴らしいと思います。どの言語などで書かれてるのかはわかりませんが、お世話になっていたらありがとうございます。 そうですね。例を挙げておくべきだったか...

    • http://anond.hatelabo.jp/20150210164113

      条件に該当するサイト、リストアップいただきありがとうございます! https://jjyap.wordpress.com/2014/05/24/installing-opencv-2-4-9-on-mac-osx-with-python-support/ OpenCVの導入解説として、初めてこの操作...

  • http://anond.hatelabo.jp/20150210030728

    俺も日曜プログラマーでよく技術系ブログの世話になるけど増田は贅沢言いすぎ。 動作環境をタイトルに入れてくれ、ぐらいしか賛同できない。俺は出来る人のメモ書きが読めるだけで...

  • 初心者が技術ブログを読む時に気を付けたい6つ心構え|ただの通りすがり

    6.感謝の気持ちは、コメントに書くことをお勧めする

  • 技術系の記事というものは省略が基本

    http://anond.hatelabo.jp/20150210030728 はてななどのブログに限らず、技術書には程度というものがあって、それぞれに用語がある。 ページや文書には必ず限りがあり、専門用語を使わずに記述...

  • http://anond.hatelabo.jp/20150210030728

    あんたはBSDもGNUも分かってないみたいだから何説明してもダメだと思う。 クズはネットなんて見んな

  • http://anond.hatelabo.jp/20150210030728

    「詳細を書かなくてもいい」けど「『別に書くまでもないこと』を書いていただきたい」というのは詰まるところ「俺のレベルに合わせろや」としか読めない。それは無理っす。

  • io.jsでmruby実装のhttp2サーバーのtrusterdを動かした

    こんばんは、今朝は次男が「いってらっしゃい」と「バイバイ」ではなく、送り出してく

  • じゃあ俺もここ2年間でたまに書いてた増田晒す!!!!

    20以上ブクマがついたやつ ブクマが少ない順に。 並べたら意外と少なかった。 ぼくの特定はしないでください。 傾向としては、プログラミング系と、女系がよく伸びている印象 べつ...

記事への反応(ブックマークコメント)