Edited at

大学入学時に知っておきたかったドキュメンテーション環境

東京理科大学アドベントカレンダー14日目 書きます @takewell です。

今回のアドベントカレンダー、僕一番のお気に入りは @piffett さんの 地頭の良い文系エンジニアに勝つ!です。

自分も似たような課題意識を持っていて、より低レイヤーなコンピューターサイエンスやアルゴリズム、ハードウェア領域なんかをもっと勉強した方がいいんだろうなと思う日々です。

とはいえ Web や モバイルのプラットフォームの方がビジネスニーズはあるのでクラフトマンシップをとるか、アントレプレナーシップをとるか、これに尽きるのかもしれません。結論はないですね。

ただし、大学入学以前まで翻ると、何を勉強するかは違うが、まずは誰でもドキュメンテーションはするだろうなということを考えました。

そして、大学からは、文書をシャープペンやボールペンで書くことよりもキーボードで書くことの方が多くなることではないでしょうか。

この2点から今回は大学のアドベントカレンダーというのもあって、自分が入学したときに教えて欲しかったキーボードでドキュメントを書く環境のあれこれをつらつら書いていこうと思います。


扱わないこと

キーボードは HHKB か Realforce か , JIS 配列か US 配列か色々論点がありますが、まあ自分に合うものを適当に見つけたと仮定して扱いません。

また、 LaTeX や bash などの環境構築もスルーします。。ぶちゃけ mac 信者が最高


ステップ

次の流れがスムーズかと思います。


  1. タイピングを快適にできるようにする

  2. カーソル移動系ショートカットを指に覚えこませる

  3. 記法を知る

  4. 適材適所な場所にドキュメンテーションして頭の整理や提出物、共有物、の環境をつくる

  5. bash を駆使する

順に説明します。


タイピングを快適に

まずはキーボードを打つのが遅い場合は訓練した方が快適なので次のサイトを使うのをオススメします。



  • e-typing 速度よりも正確性を重視して練習がオススメ


  • 寿司打 正確性よりも速度を重視して練習がオススメ


  • typing.io 日本語ではなくアルファベットの入力を快適にする


カーソル移動系ショートカットを指に覚えこませる

タイピングの際に使えるショートカットとして macOS であれば以下の keybind が使用できます。他にも Emacs , ターミナル, IDE 等でも対応されていることがあります。元々は Emacs というテキストエディタの keybind ですね。

操作
keybind


Ctrl + p


Ctrl + n


Ctrl + f


Ctrl + b

行頭
Ctrl + a

バックスペース
Ctrl + h

デリート
Ctrl + d

行削除
Command + Backspace


使えるようにしておくと良い記法


  • Markdown 記法

この Qiita もそうですが、Slack, GitHub, 後述するサービスでもほとんど Markdown 記法に対応しています。若干異なる点があったりしますが、気にしなくてもいい範囲だと思います。

一番普及しているのはおそらく commonmark という仕様でしょう


Commonmark Reference


Markdown のメリットは構造化が楽なこと、記法なので使う場所を選ばないので汎用的な点です。

なお、 Markdown はテーブルを書くのがしちめんどくさいのでこちらのサービスがオススメです。


Tables Generator



  • LaTeX 記法

こちらも数式を書くならば必須の記法です。

Qiita も対応していますね。 $\dfrac{ dy }{ dx }$

記法を使いこなすだけなので参照だけおいておきます。(厳密には LaTeX ではなく Mathjax だけど記法は同じ)


Easy Copy MathJax



どこで書くのか


Dropbox Paper

どこで文章を書くべきか、迷っているならば Dropbox Paper を試してみてください。 書き味、閲覧性、操作性において非常に秀逸です。当然ながら Markdown や Tex にも対応しています。これでいて無料!(Dropbox の無料アカウントは必要)

この機能がいい、あの機能がいいなんていうのは些細なことで、なにげない操作が気持ちよく直感的であればいい。そう勇気付けられる素晴らしい Web サービスですね。感動しますよ本当に。

なお、文書管理をするときフォルダを分けて一生懸命管理を試みるものですが、正直時間の無駄なのでフォルダを作るとしても2階層くらいに止めるのがおすすめです。検索機能が協力なのでどんな内容だったか思い出せれば検索できるはず。(そもそも内容が思い出せないドキュメントは検索する必要がない論)

共有やコメント機能なども充実しており、コラボレーションツールとしても優秀です。

また Paper API なんかも提供されており、自動化の仕組みを作ることなんかも可能です。


GitHubGist

編集履歴を閲覧しやすいものにしたい、スニペット、スクリプト

こういう場合は Gist に書きます。※GitHub アカウント必須


Google Colaboratory

レポート用の資料やちょっとした統計計算をやりたい場合に使います Jupyter Notebook というのもありますが、これを環境構築なしで実行できるようにしたサービスです。事前に多数のライブラリがインストールされていて、Python のバージョンを選択できたり GPU を使えたりと至れり尽せりです。プログラミング言語入門にも使えますね。


Visual Studio Code

エディタ戦争を回避をしなくてはならないので比較はしませんが、あらゆるプログラミング言語, Markdown や LaTeX , UML などといったあらゆる記法に対応しています。厳密にいうと公式が対応していたり、有志のユーザーが拡張を書いてくれていたりします。もしなかったとしても JavaScript で自分で拡張を書くことも可能です。お気に入りのテキストエディタが現時点でないのであれば 2018 年現在 では VSCode を選んでおけば間違いないのではと思います。


bash を駆使する

今まで Web 上で文書を編集する方法ばかりを紹介しましたが、自分の PC の中に文章をためなければいけない場面もあるかと思います。(ソースコードなど) bash を使えばテキストデータだけで構成されたファイルを,内容を検索することも置換することもできるようになります。もちろん Windows であれば エクスプローラー、mac であれば Finder で検索は可能なのですが、bash の使い方を覚えた方が自由度が高くなるので最初から bash で操作することをオススメします。

こちらが読みやすかったです。


お気楽 bash 超入門 (前編)


bash を覚えれば、例えば次のように、Markdown のファイルを全て舐めて、name という文字があれば new に置換するといったことが可能です。

$ find . | grep -E ".md$" | xargs -I sed -i -e 's/name/new/g' {}


終わりに

知ってる人からすればどれも当たり前かもしれませんね。フレッシュマンの方の役にたてば幸いです。

当然ながらツール類は流行り廃りが激しいので読んだときには廃れていても悪しからず。

以上。

明日は @ZqKjL5vm5kspDgx さんです。