ドキュメントなんとかしたい

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

Upload: shingo-tamaki

Post on 19-Jul-2015

299 views

Category:

Engineering


2 download

TRANSCRIPT

Page 1: ドキュメントなんとかしたい

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

Page 2: ドキュメントなんとかしたい

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

• Sphinx

• plantUML

• RedPen

Page 3: ドキュメントなんとかしたい

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

Page 4: ドキュメントなんとかしたい

こんな感じでは?

• 万能Excel方眼紙

• 顧客が扱い慣れている

• 重い

• Win縛り(ほぼ)

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

イケてる イケてない

Page 5: ドキュメントなんとかしたい

別のツール探してみよう

Page 6: ドキュメントなんとかしたい

Sphinx

Page 7: ドキュメントなんとかしたい

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

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

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

• LaTex的なイメージ(LaTexも互換性あり)

• SCMで管理しやすい

Page 8: ドキュメントなんとかしたい

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

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

Page 9: ドキュメントなんとかしたい

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

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

段落2です ----

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

段落3です ++++

段落4です ~~~~

段落5です ////

段落6です。 ||||

Page 10: ドキュメントなんとかしたい

plantUML

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

• jarファイル1個

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

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

Page 11: ドキュメントなんとかしたい

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

Page 12: ドキュメントなんとかしたい

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

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

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

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

Page 13: ドキュメントなんとかしたい

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

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

Page 14: ドキュメントなんとかしたい

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

Page 15: ドキュメントなんとかしたい

現時点での(私の)結論

Page 16: ドキュメントなんとかしたい

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

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

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

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