技術を伝える事の難しさ
会社の糞施策で「計画年休というのを1年分出す」という、「本当、毎回よくもまぁ、こんな馬鹿な事を思い付くもんだな。」と、天下り老害共を心の中で1024回小馬鹿にしつつ、今月は1時間休暇を無理に使用する予定を仕方なく立ててしまったため、定時の1時間前に帰宅しました。
本当は残業を2.5時間する位の状況だったので、計3時間の進捗遅れになった事から、来週小刻みに遅れを取り戻す残業をする事になるという事になります。
(＝会社は月の支払いを、より多くの残業代を追加して私に支払う事になる。┐(￣ヘ￣）┌)
さて、そのような中、仕事が中途半端で帰宅してしまったため「モヤモヤ」が取れなくなり、来週の始めから仕事をスムーズに進めるために自宅で自己啓発をするハメになったのですが(これは仕事というよりも私のノウハウを蓄積する事になる自己投資)、この自己啓発をするため、ネット検索で技術情報を収集していた際、インチキ情報に振り回され、6時間も時間が溶けました。(やっている事がマニアック過ぎて、ネットに情報が少ない事に起因します)
という事で、この自己啓発で違った意味でモヤモヤが出来てしまったので、「誤り」や「情報不足のままで」情報をネットに書き散らしているレベルの低いエンジニアを小馬鹿にする鬱憤をここに書いておこうかと。(ヒドイｗ)
◇ ◇ ◇
「ネットで検索可能な技術情報を残す」という行為は、「非常に素晴しい行為で賞賛に値する」と思っているのですが、「相手に理解できない事」、「誤った解釈を残してしまう事」などは、場合により「罪」にもなってしまうという怖さがあります。
また、これがネット検索で沢山且つバラバラな類似情報がヒットするなら、罪も軽くなるのですが、ニッチ…レア情報となると、全世界の人がこれを信じてしまいます。それが例え嘘だとしても…
そのため、「俺、ネット検索で殆んど見つからない技術情報を書いたぜ！」と思っての執筆をする場合は、かなり慎重にすべきと思っています。
【心得】
(1) その際の環境を具体的に記述する。
プラットフォーム、開発環境を具体的に。
(2) 他の人の事を思い浮べて記述する。
(3) 説明を具体的に記述する。
具体性が薄くなってしまう場合は、自分の考察を記述する。
…と、最低でもこれ位を書かないと、同じ状況で困って検索してきて人が、その通りにやって上手く行かないと、「なんだよ、この記事、糞じゃねーか！」となってしまいます。
少なくとも、(1)に具体性があれば、(1)の時点で「俺と環境が違うから、諦めるかな…」となるし、(3)の具体性が薄い、もしくは考察である事を前面に出せば、「まぁ、信憑性は薄い事を自分で謳っている位だから、仕方ないかな…」となります。
(逆説的に考えれば、(1)の事すら書いていない記事の場合、有識者にとっては「そのままスルー対象となる」のですがｗ)
悪い例…というか、いつも私が技術情報を検索して、「う～ん、これじゃぁ、ダメだな…」と思う反面教師を例に挙げると、
【ダメな例 1：ソースコンパイル】
あるソースをコンパイルする説明があるとして、
と唐突に記述してある。
これにはプラットフォームも書いていない状況などがあります。
文脈を読み解くと、macOS上だったり、Linux上だったり、酷いと、
Windows上のCygwinやMSYS2だったりします。
この場合はまだg++なので、クロス環境として考えられるのですが、
シンプルなケースでもない限り、その後は上手く行かないケースが多いです。
【ダメな例 2：状態を書いていない】
Debian系のディストリビューション(例えばLinux Mint)にて、
パッケージを
でインストールする。
一見合っているように見えて合ってないです。
この場合、
もしくは、
と、いう感じで、「Superuserの状態が必要である事を明示的に表現すべき」だったりします。
この1表現があるか無いかで、前後の文脈が変ってきたりします。
尚、パッケージ管理はaptだったり、yumだったり、dnfだったりありますが、
コマンド名でディストリビューションは分るので、流石にプラットフォームの説明は
不要だったりしますが、文章次第で「どのプラットフォームで、この文書いてんだ？」
みたいな文章もあったりするので、やはり上述の(1)は踏襲したいものです。
【ダメな例 3：既に色々な物がインストールされている事が前提となっている】
例えば「VC++(のとあるバージョン)でOpenSSLのライブラリをビルドしたい」
と思った場合、公式サイトからファイルを落して、そのファイルを
展開したとして、
と書かれているとします。
非常に具体的に書いてあるように見えて「実はポンコツ」という、
これは上級者に陥り易い流れで、この説明から、
(a) Perl が必要。
それも、どのパッケージのPerlが必要なのか書いていない。
どれでも良いのかすら分からない。
「このPerlで実行(できればバージョンも記述)」と一言必要。
(b) 前提となるアーキテクチャ(x86, x64)の説明がない。
この引数から64bitアーキテクチャというのは、素人でなければ分るが、
これを読んだ人の環境は32bitかも知れない。
(c) この状態で何も説明をしなければ、ダイナミックリンク形式の
ライブラリとなる。
それで良いのなら良いのですが、スタティックリンク形式にしたい場合の
説明が無い(＝このOpenSSLライブラリを使う人には.dllが必要になる。
変更にはMakefile内のコンパイラオプションを変えないとならないが、
その説明もない。
(d) 更に重箱の隅を突くとなると、
この例のようにコマンドラインでビルドを行うには、
Visual Studioの場合は、
「VS 20xx用x86_x64 Cross Tools コマンドプロンプト」で
ビルドをしなければならない。
Visual Studioに同梱されている「開発コマンドプロンプト」は
起動時の「環境設定が違う(起動するバッチが違う)」ため、
リンクでエラーが発生する。
標準のcmd.exeなんてサーチパスが開発向けに切られていなければ、
nmake.exeすら実行できないｗ
…と、これは一部の事なのですが、このようなボタンの掛け違いから、
その先の事が何一つ上手く行かない場合があります。
ついでに書くと、実はno-asmの説明も無いですが、これを付けないと
アセンブラ(nasm)が必要なります。
何故アセンブラを使わないのか、使うとどうなるかなど、
書く事は山程ありますが、この議題から脱線するのでここでは割愛します。
(このように理由を述べて、文を終らせる必要があります)
というような感じで、高度になっていく程、説明する事が多くなって行き、「一見有用に見えて、実はポンコツな説明だったりする事が非常に多い」です。
(スキルが高い人には、そのポンコツ情報が閃きのキッカケになる場合もあるので、全てが悪いという訳でもありません)
私の場合、不具合にハマってしまい、それを解決したようなマニアックな技術情報を書く場合はstep-by-stepで紐解く説明を書いたり、ツールをソースごと公開する場合は、言語／プラットフォーム／開発環境をバージョンを具体的に記述するようにしています。また、まっさらの環境で一度ビルドしてみたり、まっさらの環境で一度実行してみたりします。それにより不足しているものが見つかったりするので、その不足分を記述したりします。これは本業でも同じです。
趣味のレベルとしては過去に以下のような例があります。
【例：小技的なツールを公開した時の記事】
【例：マニアックものを解析をした時の記事】
【例：超マニアック過ぎて具体的な事がいかに必要になったかの記事(コメントが欄が熱い！ｗ)】
具体性は大事！(・∀・)
こんな事を偉そうに書いた訳なので、自分も反面教師にならないように、説明には具体性を持って、楽しいプログラミングライフを過して行こうと思います。
本当は残業を2.5時間する位の状況だったので、計3時間の進捗遅れになった事から、来週小刻みに遅れを取り戻す残業をする事になるという事になります。
(＝会社は月の支払いを、より多くの残業代を追加して私に支払う事になる。┐(￣ヘ￣）┌)
さて、そのような中、仕事が中途半端で帰宅してしまったため「モヤモヤ」が取れなくなり、来週の始めから仕事をスムーズに進めるために自宅で自己啓発をするハメになったのですが(これは仕事というよりも私のノウハウを蓄積する事になる自己投資)、この自己啓発をするため、ネット検索で技術情報を収集していた際、インチキ情報に振り回され、6時間も時間が溶けました。(やっている事がマニアック過ぎて、ネットに情報が少ない事に起因します)
という事で、この自己啓発で違った意味でモヤモヤが出来てしまったので、「誤り」や「情報不足のままで」情報をネットに書き散らしているレベルの低いエンジニアを小馬鹿にする鬱憤をここに書いておこうかと。(ヒドイｗ)
「ネットで検索可能な技術情報を残す」という行為は、「非常に素晴しい行為で賞賛に値する」と思っているのですが、「相手に理解できない事」、「誤った解釈を残してしまう事」などは、場合により「罪」にもなってしまうという怖さがあります。
また、これがネット検索で沢山且つバラバラな類似情報がヒットするなら、罪も軽くなるのですが、ニッチ…レア情報となると、全世界の人がこれを信じてしまいます。それが例え嘘だとしても…
そのため、「俺、ネット検索で殆んど見つからない技術情報を書いたぜ！」と思っての執筆をする場合は、かなり慎重にすべきと思っています。
【心得】
(1) その際の環境を具体的に記述する。
プラットフォーム、開発環境を具体的に。
(2) 他の人の事を思い浮べて記述する。
(3) 説明を具体的に記述する。
具体性が薄くなってしまう場合は、自分の考察を記述する。
…と、最低でもこれ位を書かないと、同じ状況で困って検索してきて人が、その通りにやって上手く行かないと、「なんだよ、この記事、糞じゃねーか！」となってしまいます。
少なくとも、(1)に具体性があれば、(1)の時点で「俺と環境が違うから、諦めるかな…」となるし、(3)の具体性が薄い、もしくは考察である事を前面に出せば、「まぁ、信憑性は薄い事を自分で謳っている位だから、仕方ないかな…」となります。
(逆説的に考えれば、(1)の事すら書いていない記事の場合、有識者にとっては「そのままスルー対象となる」のですがｗ)
悪い例…というか、いつも私が技術情報を検索して、「う～ん、これじゃぁ、ダメだな…」と思う反面教師を例に挙げると、
【ダメな例 1：ソースコンパイル】
あるソースをコンパイルする説明があるとして、
と唐突に記述してある。
これにはプラットフォームも書いていない状況などがあります。
文脈を読み解くと、macOS上だったり、Linux上だったり、酷いと、
Windows上のCygwinやMSYS2だったりします。
この場合はまだg++なので、クロス環境として考えられるのですが、
シンプルなケースでもない限り、その後は上手く行かないケースが多いです。
【ダメな例 2：状態を書いていない】
Debian系のディストリビューション(例えばLinux Mint)にて、
パッケージを
でインストールする。
一見合っているように見えて合ってないです。
この場合、
もしくは、
と、いう感じで、「Superuserの状態が必要である事を明示的に表現すべき」だったりします。
この1表現があるか無いかで、前後の文脈が変ってきたりします。
尚、パッケージ管理はaptだったり、yumだったり、dnfだったりありますが、
コマンド名でディストリビューションは分るので、流石にプラットフォームの説明は
不要だったりしますが、文章次第で「どのプラットフォームで、この文書いてんだ？」
みたいな文章もあったりするので、やはり上述の(1)は踏襲したいものです。
【ダメな例 3：既に色々な物がインストールされている事が前提となっている】
例えば「VC++(のとあるバージョン)でOpenSSLのライブラリをビルドしたい」
と思った場合、公式サイトからファイルを落して、そのファイルを
展開したとして、
と書かれているとします。
非常に具体的に書いてあるように見えて「実はポンコツ」という、
これは上級者に陥り易い流れで、この説明から、
(a) Perl が必要。
それも、どのパッケージのPerlが必要なのか書いていない。
どれでも良いのかすら分からない。
「このPerlで実行(できればバージョンも記述)」と一言必要。
(b) 前提となるアーキテクチャ(x86, x64)の説明がない。
この引数から64bitアーキテクチャというのは、素人でなければ分るが、
これを読んだ人の環境は32bitかも知れない。
(c) この状態で何も説明をしなければ、ダイナミックリンク形式の
ライブラリとなる。
それで良いのなら良いのですが、スタティックリンク形式にしたい場合の
説明が無い(＝このOpenSSLライブラリを使う人には.dllが必要になる。
変更にはMakefile内のコンパイラオプションを変えないとならないが、
その説明もない。
(d) 更に重箱の隅を突くとなると、
この例のようにコマンドラインでビルドを行うには、
Visual Studioの場合は、
「VS 20xx用x86_x64 Cross Tools コマンドプロンプト」で
ビルドをしなければならない。
Visual Studioに同梱されている「開発コマンドプロンプト」は
起動時の「環境設定が違う(起動するバッチが違う)」ため、
リンクでエラーが発生する。
標準のcmd.exeなんてサーチパスが開発向けに切られていなければ、
nmake.exeすら実行できないｗ
…と、これは一部の事なのですが、このようなボタンの掛け違いから、
その先の事が何一つ上手く行かない場合があります。
ついでに書くと、実はno-asmの説明も無いですが、これを付けないと
アセンブラ(nasm)が必要なります。
何故アセンブラを使わないのか、使うとどうなるかなど、
書く事は山程ありますが、この議題から脱線するのでここでは割愛します。
(このように理由を述べて、文を終らせる必要があります)
というような感じで、高度になっていく程、説明する事が多くなって行き、「一見有用に見えて、実はポンコツな説明だったりする事が非常に多い」です。
(スキルが高い人には、そのポンコツ情報が閃きのキッカケになる場合もあるので、全てが悪いという訳でもありません)
私の場合、不具合にハマってしまい、それを解決したようなマニアックな技術情報を書く場合はstep-by-stepで紐解く説明を書いたり、ツールをソースごと公開する場合は、言語／プラットフォーム／開発環境をバージョンを具体的に記述するようにしています。また、まっさらの環境で一度ビルドしてみたり、まっさらの環境で一度実行してみたりします。それにより不足しているものが見つかったりするので、その不足分を記述したりします。これは本業でも同じです。
趣味のレベルとしては過去に以下のような例があります。
【例：小技的なツールを公開した時の記事】
【例：マニアックものを解析をした時の記事】
【例：超マニアック過ぎて具体的な事がいかに必要になったかの記事(コメントが欄が熱い！ｗ)】
具体性は大事！(・∀・)
こんな事を偉そうに書いた訳なので、自分も反面教師にならないように、説明には具体性を持って、楽しいプログラミングライフを過して行こうと思います。
コメント
コメントの投稿
