Markdown まともに書けてない奴大杉
Markdown がなってない連中のクソ Markdown を読むのマジで苦痛。
目次
なってない Markdown の特徴
- 「空行」がなく「改行」しかない
マジでこの手の奴多すぎる。
# 見出し
本文…
- リスト
- リスト
## 小見出し
↑こういう感じで空行が全くない。見出しの前後にだけ入れる・入れないみたいな本人の中のルールがあるワケではなさそうで、不定期に空行が混じったりしている。
Markdown はプレーンテキストでも読みやすい構文であるのが特徴なのに、それを無視してレンダリングされたプレビューしか見ずに執筆しているのが丸分かり。
こういう奴の何が悪いかって、そいつが書いた空行のない汚い Markdown 文書を、他の人が加筆修正する場面のことを全く想像していないバカであることがミエミエだからである。
こういうタイプは自分の目線だけで物事を判断するタイプのバカで、保守性とか他人の苦労とかを微塵も考えていない。直したいと思った文章が Markdown 中のどこにあるのか探すハメになる他人の苦労を一切考慮していない。
こういう奴は Markdown に限らずソースコードも他のドキュメンテーションもクッソ汚くて、文章の意味も全く他人に伝わらないゴミを量産するだけのカスなので、Markdown 云々のレベルじゃなくて育ちの問題なんだけど。
- コードスパン・コードブロックを使わない
コードブロック (pre 要素になるヤツ) はまだ使える人もいるけど、コードスパン (文中に code 要素で書く、←こういうヤツ) を全く使わない奴が結構いる。マジで何なんだろうか？お前のキーボードにはバッククォートキーが付いてないのか？ 単純にバッククォートの打ち方が分からないんだろうな。そんな体たらくでお前はどういうコードが書けるというの？
文中に登場するコマンドや変数名なんかをコードスパンで囲むことで、記号類の余計なパースを回避できるし、何よりレンダリング時に code 要素でスタイリングされて読みやすくなる。前述のようにどうせプレーンテキストの状態を無視してプレビュー欄しか見ないで Markdown を執筆してるクセに、その見栄えすら気にならないのってマジで無神経なんだけど。
結局アンダースコアやアスタリスクが出てくるソースコードをコードスパンで囲まないから意図しないパースがされてるのに、そのミスにも気付いてないし。
- 文章をすぐ改行する・でも「行末2スペース」は入れていない
CommonMark なんかの仕様上は、「行末に2スペース」を入れることで強制改行 (br 要素) が入れられるが、Markdown のパーサによっては、親切心なのか、2スペースなしでの改行でも br 要素による強制改行を実現してくれる。
「テキストの表示幅は閲覧者のデバイスによって異なるのだから、自分の環境で見た目が良いからといって強制改行を入れるな」という話って、もう21世紀初頭に語り尽くされた話題だよね？今さらそんな古い忠告させないでくれる？昔の HTML メールみたいに行末の2・3文字が折り返されて強制改行が入る、あの気持ち悪い状態になってんだわ。
長い文章を自分の環境で目視確認して強制改行してしま
うと、
こういう風に気持ち悪い折り返しが発生します。
前述の「コードスパン」と比べたら、見栄えを気にする意識があるのは結構だが、それも「自分目線だけ」で判断してるから他人の環境でクソな Markdown になるんだよなぁ。
強制改行は家族を人質に取られても絶対に入れるな。
ロクでもないクソ Markdown を書く奴は HTML が分かってない
この手の気持ち悪い Markdown を書く奴は、そもそも Markdown の成り立ちや役割、パーサと変換後の HTML の仕様が分かっていない。いや、分かろうともしていない、という感じだろうか。
Markdown の元々の思想は、「プレーンテキストでも読み書きがしやすく、それを HTML へと変換できるフォーマット」であることは Wikipedia にも書かれている。
- 参考 : Markdown - Wikipedia
だから、Markdown はそもそも、プレーンテキストの状態で読みやすく書かなければならないのだ。それを HTML にパースするのか、パワーポイントか LaTeX か他の形式に変換するのかは閲覧者次第ともいえるワケだ。
なのにプレビュー欄ばっかり見て執筆しているから、プレーンな Markdown 側に空行が入っていて読みやすいかとか、そういうことを気にしていないのである。前述のとおり、Markdown のレベルで汚らしい書き方になる奴は他の言語のソースコードも汚いし、それはすなわち「他者目線」が完全に欠落している迷惑な奴であることがひと目で分かるので、大嫌いなのだ。
そして、いざ HTML に変換された後、自分が書いた Markdown がどんな風にパースされるのか全く想像がついていない奴も多い。「なぜかココに空白が入っちゃうんですけど…？」とかいって、何が起きているのか全く理解できていない。そんな奴は Markdown 書くな。まず HTML を勉強しろ。分からないモノを分からないままにして使うのは禁止だ。絶対ダメだ。
Markdown には方言が多く、
- パーサによって解釈が異なってしまう記法があったり (アンダースコアによる強調など)
- テーブル構文が使えたり使えなかったり、アラインメント指定ができたりできなかったり (GFM など)
といった問題が起こりやすい。「VSCode で下書きしてる時は問題なかったんですけどー」なんていう話はよく耳にする。そんな些細なミス一度たりとも犯すなよバカがとは思うが、独特な仕様のパーサも時々あったりするので、分かち書きを忘れるくらいは許容してやろう。しかし「分かち書き」という概念すら知らない奴は、Markdown や HTML 以前に日本語・英語の文法が分かってなさすぎるのでぶっ殺したくなる。
「Markdown は HTML の糖衣構文なんだ」という感覚があれば、「Markdown を書いている」という状況はイコール「(このあと HTML へと変換される) ソースコードを書いている」という感覚になるはずだし、ソースコードを書いているつもりがあれば、読み手のために分かりやすくする空行を入れるとか、コードスパンや強調で意味付けをする、といった配慮ができるはずだ。
そういう知識もなく、何となく人気らしいからという理由だけで Markdown を取り入れようとして、Markdown の執筆だけで一生懸命な余裕のない奴が、その知能を据え置きにしてクソ Markdown を書き続けるのがムカつくのだ。
Markdown で表現が難しい図表の扱いを設計しきれているか？
CommonMark の中にはテーブル記法は存在しない。GFM がテーブル記法をサポートしているものの、各パーサが GFM のテーブル記法を完璧に実装できているかどうかは怪しく、バグが起こりやすい。
また、テーブルは垂直アラインメントを揃えにくい。「VSCode で Markdown を書いているなら当然等幅フォントを使っているだろう」と思ったらプロポーショナルフォントで書いてる奴もいて、そういう奴がプロポーショナルフォント上で「それっぽく罫線が揃っている」ような Markdown をよこしてくると、等幅フォントで表示しているコチラの環境ではグチャグチャに見えたりする。自分はまだ遭遇したことはないが、Source Han Code JP のように「半角・全角比」が「1 : 2」ではない等幅フォントを使っているような人がいるとその場合も結局垂直アラインメントが揃わず気持ち悪くなる。かといって垂直アラインメントをしない方針にすると、すぐにバーティカルバーを書き忘れるバカが出てきて困る。
- まさかとは思うけど Markdown を書こうとしてる奴で「プロポーショナルフォントって何？」とか言う輩はいねえよな？そういう奴は Excel の印刷ズレとかに文句言う資格ねえからな。使うツールの仕組みや知識も持たずに、曖昧な指示で理想どおりの出力がされると思うなよ
図に関しては、Markdown 内に PlantUML などを書ける拡張が存在したりしているものの、PlantUML のインストールに失敗していて「上手く動かないんで、公開のレンダリングサーバを使いましょう」とかいって平気で情報漏洩させるバカがいたり、とにかく知識とリテラシーが不足している。
Markdown は HTML の糖衣構文といえ、プレーンテキストでも読みやすいフォーマットとしてラフに設計されたモノだから、表は table 要素を直接マークアップすれば良いし、図は画像ファイルとして埋め込めば良い、というのが、当初の Markdown の思想であろう。だから結局、Markdown はその仕様としては図表の扱いが弱いワケだが、こういうフォーマットを使って「システム構成図を書こう」「画面設計書を書こう」と考える輩は、ドキュメンテーション能力が欠落していると言わざるを得ない。
- テーブル記法は面倒臭いので、表データは別途 Excel で書きます
- → Markdown しか読んでない人が Excel ファイルの存在に気付かない
- → 後出しで方針を決めたから両文書の読み方やメンテナンス方針が定まっておらず、Excel と Markdown とで情報の整合性が取れなくなっている
- 図は PlantUML 等の外部ツールを使って、Markdown 内に DSL を埋め込みます
- → その外部ツールの環境構築方法がガイドされず、つまづくメンバ続出
- → 汎用性の低い DSL を覚える学習コストがかさんで執筆タスクが遅延する
…こういう思慮の浅い方針宣言に付き合わされて、くだらないトラブルが続出している案件は幾度となく見てきた。
本質的に図表が扱えない、文章だけで構成される Markdown というフォーマットを採用しておきながら、HTML という「文章への意味付け = マークアップ」の概念もロクに知らずに何かを執筆しようとしたって、分かりやすいドキュメントが生まれないのはすぐに分かることだろう。
数々のトラブル・問題・厄介事の根本原因は、その殆どが「Markdown とその周辺技術に対する知識が足りていない」ことに起因するが、3分の1くらいは「そもそもその問題を解決する手段として Markdown が最適とはいえないことに気付いていない」というモノがある。釘を打ち込みたいと言っているのに「丈夫なカッターナイフ」を編み出そうとしている感じ。いやトンカチ使えよ、みたいな。Markdown じゃないツールで書いた方が良くね？ という場面はごまんとある。
このツールさえ使えば万能だとか、このフォーマットの方が良いとか、そういう優劣の話がしたいワケじゃない。
- まず「Markdown とは何なのか」「Markdown が得意なこと」「Markdown が不得意なこと」という仕様を理解し、
- 次いで「これから作りたいモノに対して、Markdown というツールは最適なのかどうか」を判断し、
- どこまでを Markdown で書き、どこから先を別ツールに担当させると効果的なのか、役割と方針を決め、
- そのルールを「新規執筆時のルール」「加筆修正時のルール」として明文化しメンバ全員に従わせる
という、文書執筆におけるアーキテクチャ選定とルール策定・組織のガバナンスが出来ていないのだ。
Markdown はモダンなんだとか勘違いして、「Markdown で書いてる俺カッコイイ」がやりたいだけで物事を決めるのは、組織に不必要な混乱をもたらす。目的と手段が逆転している典型例だ。Markdown は素人が想像するような「素晴らしい万能フォーマット」ではない、ということを理解してほしい。
コレまで書いてきたように、「そもそも日本語・英語の文法やビジネス文書の知識」もそうだし、「パーサ」とか「HTML 構文」とか、そういう周辺の技術知識も持ち合わせていないと使いこなせないのが Markdown であり、「図表をどう扱うと、新規執筆から運用保守フェーズにおける加筆修正までこなせそうか」などという設計がかなり難しいので、要求スキルレベルは低くないと思った方が良い。そこでさらに PlantUML 拡張を使おうーだなんて思いつきで始めたらどういう混乱が生じるか、ホームラン級のバカじゃなければ分かるはずだ。
Markdown を扱うためのスキルレベル的に、「Excel のこういうところが使いにくいんですよねーｗ」とか平気で言えちゃう程度の、原因を調べて問題を自分で解決できないような輩には、Markdown でのまともな執筆は無理だと思う。「自分の環境では書けたようにみえる」が関の山で、それを他人の環境でも同じようにパースして読めるのか、パースされた結果が文章として読みやすいのか、ある程度時間が経ってからその文書をメンテナンスしようと思った時に加筆修正がしやすい状態で残せているか、といったことが全く考慮できていない、クソ Markdown しか書けないことだろう。
ジョエル・スポルスキの「抽象化は作業時間の節約をするが、学ぶ時間までは節約しない」という言葉が、ココ最近の技術業界ではよく目立つなぁと思う。
Markdown は HTML の糖衣構文。TypeScript は JavaScript のスーパーセット。Kubernetes は仮想環境の抽象化層。それぞれの「流行りのモダンな技術」の裏には、古くからある原始的な技術が健在であり、その原始的な技術領域をマスターできている人にとっては、その「モダンな抽象化層」によって作業が省力化できたりするワケだ。決して、「根本の技術を知らずとも、何も考えずに利用できるようになった」ワケではないのだ。
Markdown で書いた文書のプレビューがおかしかったら HTML の構文が「見え」ないと (想像・デバッグできないと) 直せないし、ECMAScript の構文と TypeScript の構文の区別も npm の仕組みも分かっていない人は TypeScript のトラブルを回避できないし、Kubernetes 裏側では結局各クラウドベンダの実装に合わせて EC2 や LB をイジれるぐらいの知識が必要になる。
このクラウド時代に、原始的な技術をどこでどうやって学び身につけるか、という課題はあるが、いずれにしろ「その技術が隠蔽している裏側の事情」が分かっていない人は、結局その抽象化層も使いこなせないし、視野が狭いままで、長期間生き延びる成果物を作れないし、トラブル対応能力が養われない。
上っ面だけモダンな気分でいる奴の成果物をレビューしたり保守したりする立場になると、こういう無神経な成果物が本当にムカつくのだ。思ったとおりのバグり方をし、想定した年月で廃止・代替されたりする。そういうクソつまんないモノを作るのに関わるのはウンザリだ。一度作ったらしばらくは放置して生存でき、変更が必要な時もコストがかからないモノを作りたい。それはソースコードでもドキュメントでもインフラでも同じことで、「早く仕事を完成させて手放したい」「完了した仕事の面倒を見ないで済むようにしたい」 と思っているから、上っ面だけのクソ成果物は嫌いなのだ。
