最近、仕事でドキュメントを書く機会が増えたので、実際に使用して良かったツールをまとめておく。他に良さそうなツールが何かあれば、今後も追加予定。

LaTex

理系の身からすると、論文を書く際によく出てくるツールだが、これが数十ページのドキュメントを書く際には、目次の自動生成機能が特に強力で、文章の本文を書くことのみに集中できるのが良い。

おそらく、LaTexはMicrosoftのWordあたりと比較されるのだろうけど、WordはバージョンによってはGUIの変更によって機能の使い方がよく分からないということがあると思うが、LaTexに関しては、それ自体が枯れたマークアップ言語であるので、一度LaTexの記法させ覚えれば、特にその後記法に大きな変更もなく、操作に迷うこともないだろう。また、LaTexはインターネット上に知見も多いので、よほど高度なレイアウトを実現しようと思わない限りは、レイアウトを実現するための記法が分からなくて文章を意図するようにレイアウトできない、ということはない。

LaTex使っているとマークダウンで良いのでは？と言われることがある。マークダウンの表現の幅とLaTexの表現の幅を比較した場合に、LaTexが圧倒的に優れているため、比較対象としてWord並の柔軟さということを考えると、マークダウンよりもLaTexに分配が上がる。

ちなみに、自分のメモ用にはマークダウンを使っている。ここでいうドキュメントとは、あくまで社内・外で共有するようなある程度レイアウトの柔軟さが要求されるドキュメントのことである。
LaTexのフロントエンドは世の中に色々あると思うが、自分の場合はMac環境にてTexPad(有償)を使用している。IDEのような感じで、とても使いやすい。また、原稿がコードベースのため、Gitで管理しやすい。

OpenAPI (旧：Swagger)

OpenAPIは、REST APIのドキュメンテーションツールである。Web APIの実装の環境で、モダンなあたりだとGraphQLなんかが出てくると思うが、逆にそうでない場合はだいたいREST APIの形式が多いような気がするので、Open APIがドキュメントの選択肢の候補となる。

Open APIのフロントエンドもかなり選択肢が多いので、好きなものを選べば良いと思う。自分の場合は、VSCodeにOpenAPI対応のプラグインを入れて、Redoc(redoc-cli)でHTMLドキュメントを出力している。

Plant UML

Plant UMLはシーケンス図やコンポーネント図など、多くのシステム向けドキュメントを書くのに適したマークアップ言語の環境だ。最近使い始めて、コードベースで図が描けるため、システム構成の変更に強い点が特に気に入っている

例えば、MicrosoftのPowerPointあたりで描いた、精緻にレイアウトした構成図があったとする。ある時に構成が変更になったとすると、既存の構成図で、レイアウトされている要素を1つずつ丁寧にずらして新しい要素を配置したり、非常にストレスな作業をすることになる。これは、PowerPointに関わらず、GUIベースの環境で構成図を描いた場合に必ず発生する問題だ。

一方で、PlantUMLは、図上のコンポーネントはすべてコードで表現されるため、新しい要素が追加された場合には、コードをいくつか追加すれば、既存のレイアウトを気にせずに、自動でレイアウトがされる。これは、開発時、仕様があまりまとまっていない段階などで、「何か手書きより綺麗なドキュメントが欲しいね」というシチュエーションに適している。変更が激しくても、構成図の保守で一番面倒なレイアウトの修正は、PlantUMLが自動でやってくれるからだ。

mmiyauchi

プログラムを書きながらTranceを聴くのが良いですね。みなさんも聴いたほうがいいですよ、Trance。EDMよりハードトランスでしょ。