ドキュメントなんとかしたい
TRANSCRIPT
![Page 1: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/1.jpg)
ドキュメントなんとかしたい流行りのツールを使ってドキュメントを 手早く作れないか検討してみた。
![Page 2: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/2.jpg)
アジェンダ• 主なファイルフォーマットについて
• Sphinx
• plantUML
• RedPen
![Page 3: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/3.jpg)
主なファイルフォーマット イケてるトコ&イケてないトコ
![Page 4: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/4.jpg)
こんな感じでは?
• 万能Excel方眼紙
• 顧客が扱い慣れている
• 重い
• Win縛り(ほぼ)
• バージョン管理しづらい(xlsx形式でも見づらい)
イケてる イケてない
![Page 5: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/5.jpg)
別のツール探してみよう
![Page 6: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/6.jpg)
Sphinx
![Page 7: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/7.jpg)
Sphinx• pythonで書かれたドキュメント生成ツール
• プレーンテキスト(reStructureText)から出力フォーマットを選択可能(HTML,PDF,etc)
• プラグインで機能拡張(他のmarkdown形式もプラグインで対応可能)
• LaTex的なイメージ(LaTexも互換性あり)
• SCMで管理しやすい
![Page 8: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/8.jpg)
こんな感じのHTMLが出力されますreStructuredText入門
http://docs.sphinx-users.jp/rest.html
![Page 9: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/9.jpg)
テキスト内容サンプル1 =====
テキストはrestructuredTextという種類のマークアップ形式で記述します。 reStructuredText入門 http://docs.sphinx-users.jp/rest.html
段落2です ----
*イタリック* にしたり、**強調** したり、`code sample` のような表現がインラインマークアップで可能です。
段落3です ++++
段落4です ~~~~
段落5です ////
段落6です。 ||||
![Page 10: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/10.jpg)
plantUML
• UMLをプレーンテキストから出力するツール
• jarファイル1個
• 全ての描くならGraphvizも必要
• SphinxにpluginがあるのでSphinxのドキュメント内に記述可能
![Page 11: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/11.jpg)
Sphinx内で記述するとこんな感じ
![Page 12: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/12.jpg)
テキスト内容サンプル3 ====
palntUMLを試してみよう ---- .. uml::
actor ユーザA as userA participant アプリ as app
userA -> app: アプリ操作 alt 処理成功 app -> userA: 成功メッセージ表示 else 処理失敗 userA <- app: 失敗メッセージ表示 end
![Page 13: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/13.jpg)
RedPen• プログラミング言語の静的解析ツールのような明らかな誤りやフォーマット異常の検出を行う
• 自然言語処理等の高度な解析ではない
![Page 14: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/14.jpg)
試す時間ありませんでした…アップデート時になんか書きます。
![Page 15: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/15.jpg)
現時点での(私の)結論
![Page 16: ドキュメントなんとかしたい](https://reader036.vdocuments.pub/reader036/viewer/2022071816/55ab0e221a28ab880c8b489f/html5/thumbnails/16.jpg)
こう使えそう• 顧客への納品物としての適用は厳しい
• 社内用ドキュメントとしては有効
• RedPenは指摘するのもウンザリするようなミスを減らせるのでうまく使えば全範囲的に適応可能
• plantUMLのみの使用もUML図作成に有用