ドキュメントなんとかしたい
Post on 19-Jul-2015
299 Views
Preview:
TRANSCRIPT
ドキュメントなんとかしたい流行りのツールを使ってドキュメントを 手早く作れないか検討してみた。
アジェンダ• 主なファイルフォーマットについて
• 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
段落2です ----
*イタリック* にしたり、**強調** したり、`code sample` のような表現がインラインマークアップで可能です。
段落3です ++++
段落4です ~~~~
段落5です ////
段落6です。 ||||
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図作成に有用
top related