ドキュメントなんとかしたい流行りのツールを使ってドキュメントを 手早く作れないか検討してみた。

アジェンダ• 主なファイルフォーマットについて

• Sphinx

• plantUML

• RedPen

主なファイルフォーマット イケてるトコ＆イケてないトコ

こんな感じでは？

• 万能Excel方眼紙

• 顧客が扱い慣れている

• 重い

• Win縛り(ほぼ)

• バージョン管理しづらい(xlsx形式でも見づらい)

イケてる イケてない

別のツール探してみよう

Sphinx

Sphinx• pythonで書かれたドキュメント生成ツール

• プレーンテキスト(reStructureText)から出力フォーマットを選択可能(HTML,PDF,etc)

• プラグインで機能拡張（他のmarkdown形式もプラグインで対応可能）

• LaTex的なイメージ（LaTexも互換性あり）

• SCMで管理しやすい

こんな感じのHTMLが出力されますreStructuredText入門

http://docs.sphinx-users.jp/rest.html

テキスト内容サンプル1 =====

テキストはrestructuredTextという種類のマークアップ形式で記述します。 reStructuredText入門　http://docs.sphinx-users.jp/rest.html

段落２です ----

*イタリック* にしたり、**強調** したり、`code sample` のような表現がインラインマークアップで可能です。

段落３です ++++

段落４です ~~~~

段落５です ////

段落６です。 ||||

plantUML

• UMLをプレーンテキストから出力するツール

• jarファイル1個

• 全ての描くならGraphvizも必要

• SphinxにpluginがあるのでSphinxのドキュメント内に記述可能

Sphinx内で記述するとこんな感じ

テキスト内容サンプル3 ====

palntUMLを試してみよう ---- .. uml::

actor ユーザA as userA participant アプリ as app

userA -> app: アプリ操作 alt 処理成功 app -> userA: 成功メッセージ表示 else 処理失敗 userA <- app: 失敗メッセージ表示 end

RedPen• プログラミング言語の静的解析ツールのような明らかな誤りやフォーマット異常の検出を行う

• 自然言語処理等の高度な解析ではない

試す時間ありませんでした…アップデート時になんか書きます。

現時点での(私の)結論

こう使えそう• 顧客への納品物としての適用は厳しい

• 社内用ドキュメントとしては有効

• RedPenは指摘するのもウンザリするようなミスを減らせるのでうまく使えば全範囲的に適応可能

• plantUMLのみの使用もUML図作成に有用