普段思ったことや、雑記。

Menu & Search

今後使い続けようと思う業務向けドキュメンテーションツール

2019年11月24日

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

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が自動でやってくれるからだ。

Article Tags
mmiyauchi

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

Related article

Forkwell主催 Front-End Study #3「『当たり前』をつくりだすWebアクセシビリティ」に登壇しました

2021年1月13日…

実際に使われたセンスの良い「退職」の表現

皆さんがセンスが良く…

観測範囲におけるITフリーランス界隈での「できる(と言われる)エンジニア」の特徴

ITフリーランス市場…

Discussion about this post

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください

Type your search keyword, and press enter to search