社内ゆるふわLT会の資料

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

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

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

4. こんな感じでは？
• 万能Excel方眼紙
• 顧客が扱い慣れて
いる
• 重い
• Win縛り(ほぼ)
• バージョン管理しづらい
(xlsx形式でも見づらい)
イケてる イケてない

5. 別のツール探してみよう

6. Sphinx

7. Sphinx
• pythonで書かれたドキュメント生成ツール
• プレーンテキスト(reStructureText)から出力フォーマットを選択
可能(HTML,PDF,etc)
• プラグインで機能拡張（他のmarkdown形式もプラグインで対
応可能）
• LaTex的なイメージ（LaTexも互換性あり）
• SCMで管理しやすい

8. こんな感じのHTMLが出力されます
reStructuredText入門
http://docs.sphinx-users.jp/rest.html

9. テキスト内容
サンプル1
=====
テキストはrestructuredTextという種類のマークアップ形式で記述します。
reStructuredText入門 http://docs.sphinx-users.jp/rest.html
段落２です
----
*イタリック* にしたり、**強調** したり、`code sample` のような表現がインラインマークアップで可能です。
段落３です
++++
段落４です
~~~~
段落５です
////
段落６です。
||||

10. plantUML
• UMLをプレーンテキストから出力するツール
• jarファイル1個
• 全ての描くならGraphvizも必要
• SphinxにpluginがあるのでSphinxのドキュメ
ント内に記述可能

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

12. テキスト内容
サンプル3
====
palntUMLを試してみよう
----
.. uml::
actor ユーザA as userA
participant アプリ as app
userA -> app: アプリ操作
alt 処理成功
app -> userA: 成功メッセージ表示
else 処理失敗
userA <- app: 失敗メッセージ表示
end

13. RedPen
• プログラミング言語の静的解析ツールのよう
な明らかな誤りやフォーマット異常の検出を
行う
• 自然言語処理等の高度な解析ではない

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

15. 現時点での(私の)結論

16. こう使えそう
• 顧客への納品物としての適用は厳しい
• 社内用ドキュメントとしては有効
• RedPenは指摘するのもウンザリするようなミ
スを減らせるのでうまく使えば全範囲的に適応
可能
• plantUMLのみの使用もUML図作成に有用