masablog

Keep it simple, stupid

markdown で全てのドキュメントを書くには?

tech

ソフトウェアの評価

一般的にプログラミングをしない人がプログラミングの仕事を依頼するものであるから
ソースコードがいかにすばらしくても、それが正当な評価を受けることは少ないだろう。1
我々が機械式の時計の中身についてよくわかっていないのと同じように
我々の客もプログラミングについて無知であることは疑いようがない。

ソフトウェアの評価は「早く動く」などのわかりやすいものを除けば
ドキュメントがしっかりあって使いやすいとか、
「今こんな作業しています」と綺麗な書類で報告がくる
などの理由を大きなパラメータとして決まってくるのは明らかだ。

したがって、ドキュメントを適当に書いたり、書かなかったりすると
妥当な評価を受けられないのは自明の理となる。

ドキュメントを書くのが嫌いな理由

しかし、プログラマはドキュメントを書くことが嫌いだ。2

なぜ嫌いなのか?

  1. Word Excel Powerpoint Adobe の類の意味不明なソフトウェアで書くことを強制されており、それらはバイナリファイルなので、github 全盛のこの時代に git で diff とって管理できないから。3
    受け取った側が簡単に改ざんしたりミスでデータを変更したりできる形式でドキュメントを送りつけるのはいかがなものか?
    それはユーザーフレンドリーじゃないし、ドキュメントの性質上ふさわしくない。

  2. 自分の好きなエディタで編集できないから4
    意味不明な理由で不自由なソフトウェアを強制されることほど無意味なことはない。

  3. 作業に時間がかかるから5
    作業時間の大部分をドキュメントに使うのは馬鹿げていると思うから。
    有能な大工なら鉋の手入れに時間をかけ、手に馴染むように鍛錬を怠らないであろうが、
    プログラマにとっての鉋はエディタであり、Word Excel Powerpoint Adobe の類は鉋ではない。

改善案

  1. git でドキュメントを管理できる

  2. 自分の好きなエディタで編集できる

  3. 時間をかけずにできる

を満たせば嫌いにならずにドキュメントを書けるはず。

ドキュメントの起点は markdown6 にして git で管理し

markdown → LaTeX → pdf

コマンドで github の README 並の pdf がすぐできるから時間がないときはこれを提出する。
LaTeX なので他の形式にもできるのもいい。
pdf だからユーザーがデータを変更できないのでユーザーフレンドリーだ。
データを変えてしまうリスク7を考えなくてもいいしスマホでも読めて便利だ。

時間があるときはさらに

pdf → SVG でデザイン → pdf

でドキュメントに装飾を施せばいい。

時間が無いときも、あるときも、同じメソッドチェーンに乗っているので 一本道でやりやすく二段構えな感じがよいと思う。
やはり何事もシンプルにしておくことが肝要である。

install

LaTeX と pandoc を利用して
markdown から pdf に一発で持っていける環境を用意しよう。

sudo pacman -S pandoc texlive-langjapanese texlive-latexextra
sudo pacman -S poppler poppler-data inkscape
markdown → LaTeX → pdf

markdown ファイルを一発で pdf にする

pandoc draft.md -o document.pdf -V documentclass=ltjarticle --latex-engine=lualatex

draft.md が原稿
document.pdf はドキュメント

[ヤフー](http://yahoo.co.jp)
![画像](sample.png)

リンクや画像、表、注釈などが使える。
画像は github の同じディレクトリに入れておけば OK

時間がないときはこれで作業は終わり。
ファイルは github においた。

他にも nodejs-markdown-pdf などのツールもあるが
いったん LaTeX にしたほうが画像や表や注釈など使えてよかった。

LaTeX にすると対応形式が増えるメリットがあるが、
それらを使わないなら nodejs-markdown-pdf のほうがお手軽だし
nodejs なので css も使えるし悪くない選択になる。

SVG でデザイン(時間とやる気がある時ヒマな時ともいう)

pdf を inkscape に poppler を使って取り込んで svg 化する。
document.pdf を inkscape で開きインポート設定で poppler を使用してインポートを選択する。

inkscape での作業が終わったら pdf に戻して完成
emacs の学習曲線と黄色い四角と表の背景を青にしてみた。8

この方法は markdown に変更があったらまた装飾する作業が発生するから
ドキュメントのバージョンが 1.0 でもう変更がないときじゃないと使いにくい
やはり無駄な装飾など施しても何のメリットもない。
競合に勝つために本質的な部分に時間を注ぎ、ユーザーに価値を届けていればこのようなレッドオーシャンに首をつっこまなくてもいいはずだ。
時間は限られた資源なのだから、それを何に使うかが成否を分ける鍵であると思う。

   


  1. 時間がないから依頼する場合もあるが、それでもソースコードは読まないだろう [return]
  2. オレ調べなので知らんけどな [return]
  3. excel を表計算に使うのはまだわかる。powerpoint をプレゼンに使うのはまだわかる。ドキュメントは表計算でもプレゼンでもない [return]
  4. emacs ライクな Excel はない emacs で動く excel っぽい何かはあるが [return]
  5. 作業時間の半分くらいかかるときもある。Word Excel Powerpoint Adobe の類が嫌いなので時間がかかる。ソースコードを改造することもできないし、嫌いなのでする気もない。 [return]
  6. markdown を簡単に扱えないエディタなら捨てるのを検討すべき [return]
  7. pdf でもやろうと思えば改ざんできるが普通の人はしないしできないと思う [return]
  8. このような無駄な装飾こそ時間の無駄である [return]

11 Nov 2016 #emacs #linux

このエントリーをはてなブックマークに追加