memorandum
タグ
言語

マークアップ言語によるドキュメント作成

2019/02/18
2021/02/25
yEd Markdown AsciiDoc

大げさなタイトル？な感じもするが、MarkdownかAsciiDocで技術ドキュメントを書けないかなと改めて調べたことを記録する。

結論としては、MarkdownとyEdが良さそうだと思っている。
(すぐにまた評価が変わるかもしれないが…)

前提

  • クラウドサービスは利用しない
    • デスクトップアプリやオンプレミスなサーバにインストールできるOSSツールなどを利用

言語

AsciiDoc

  • Pros: テーブルなど詳細な書式が指定可能。
  • Pros: 亜種がなく仕様が明確。
  • Cons: 環境構築が面倒。手軽という人もいるが、VSCodeやTyporaなどエディタのみで完結するMarkdownに比べたら面倒なのは間違いない。
  • Cons: 文法がMarkdownほど知られておらず、学習コストが発生する。
  • Cons: 非エンジニアの利用の障壁も上がる。

Markdown

  • Pros: 人気＝各種ツールの対応が多い。非エンジニアでも普通に書けるのがGood
  • Cons: 亜種が多いため、標準記法を定めないと各自の環境(エディタ)でしか表示できない表現が使われてしまう
  • 編集/プレビュー環境
    • Typora
      • 非エンジニアでも触りやすい
    • VSCode
      • エンジニアはこちらか
      • MPEでプレビュー

図をどう表現するか？

  • Excel/PowerPointのオートシェイプでの作図の手軽さは重要
    • UMLなどで表現できるものならmermaid, PlantUMLなどで対応可能だが。
    • 設計の初期段階など、あまりUMLの表現にとらわれずにイメージを描きたい。
    • また、Markdownで書くなら図だけExcelを開くようなことは避けたく、Markdownに埋め込みたい。
    • Excel/PowerPointでも良いが、キャプチャなりエクスポートなりした画像をセットで管理する運用だと、その画像のとり方が属人的になり再現性が低い。
    • MarkdownにPlantUMLを埋め込んだり(GitLabだと外部サーバが必要)AsciiDocのように各種ツールを入れて生成するのも良いのだが、そこまで環境構築に手間がかかると(メンバー含めた)整備が大変だし、ツールに制限されるのが問題になる可能性もある。
    • 元ファイルがOfficeでも良いが、出力される画像が安定する方式が良い。
  • テキストファイルであるSVGが良さそうと考えたが…
    • VS Codeの標準のプレビューでも読み込める
    • Typoraでも読み込める
    • 編集が問題。だから編集用のソフトを探す？
      • Inkscapeで編集はできるが目的が違うため難
    • Excelオートシェイプのような操作感でSVGファイルとして管理できるものがあれば…
    • draw.ioが良さそう。
      • 図が豊富に作れるようだがクラウドサービス
  • と思ったが…
    • GitLabではgitlab.comの11.7.5-ee(2019/2/10時点)でもsvgはmdで表示できないようだった。
    • コミットの差分を見ても、画像のほうがわかりやすい。
      • onion skinでスライドしながら変化が見られるため。
      • SVGはテキストとして差分が出てくるため、少し変えただけでもだいぶ変わってしまう可能性がある。
    • ということでSVGに拘る必要はない。
    • しかしながら、PNGでも何でも、編集後に期待通りの形で安定して簡単に出力がしやすいツールを選ぶことが重要。
    • CIで元ファイルから変換して出力・コミットさせるような方法も考えられるが、そこまで煩雑にする必要はない。今ターゲットとするのは、プロジェクトの序盤に検討するような全体のイメージ図やちょっとした補助的な図であり、手動でツールからPNGを出力する運用でもそう困らない。ただしシステム構成などメンテナンスは必要な可能性のある図で、編集手段は用意する必要tがあるという想定。

図を編集するアプリケーションとしてはdraw.ioが秀逸だが、その代わりのDesktop Appはないか？

yEd

  • 良さそう
    • 日本語の解説記事は少ないけど…
  • yWorksが開発
  • マルチプラットフォーム
  • データファイルはテキスト(.graphml)
  • 普通にSVGエクスポートすると適切な範囲で切り出してくれる
  • パレットとして他のgraphmlから読み込みも可能
  • 全選択してCopy to System clipboardすればExcelに画像として貼り付けられる

LibreOffice Draw

  • OSS
  • Officeの操作感なのが良い
  • データファイルはバイナリ(.odg)
  • GitLabではSVGのプレビューが正しく表示されなかった。
  • PNGへのエクスポートは縦横比が崩れてNG。

OpenOffice Draw

  • LibreOfficeと同じ。LibreOfficeの方が操作しやすい印象だが、アイコンはこちらが充実？
  • こちらは縦横比が崩れることはなかった。こちらのほうが良い？
  • オブジェクトを全選択してからエクスポートして、選択範囲をエクスポートするようにすれば余白は含まれない。
  • 透過率を保存、としなければ背景色は透過しない。
  • GitLabでの表示はできているようにも見えるが顔の画像の色がはみ出していた。

Pencil

  • 重い。
  • 画像のせいかもしれないが、SVGファイルが大きい。
  • バイナリファイル(epgz, epz)。
  • GitLabではSVGのプレビューが正しく表示されなかった。

メジャーなツールとは言えない気がするので不安がなくはないが、yEdが一番良さそう。

ツール自体は日本語化はされていないため慣れが必要と思われるが、こんな図はどう書くの？という確認のために触ると思うのでその記録もこのブログに残していきたい。

今回いろいろ試行錯誤したファイル群は以下に残している。
https://github.com/ksoichiro/document-test

© 2010 ksoichiro