Markdownでドキュメントを管理する上での悪い点

Question

業務で色々な製品のドキュメントを作成したり翻訳したりしているのですが、ぼんやりと何某かの製品に関するドキュメントはMarkdownで記述してGitとかでバージョン管理していくのが理想なんじゃないかと思っています。

Markdownとの比較対象はMicrosoft WordやAtlassian Confluenceなどです。自分なりの良い点/悪い点の比較は、以下の感じです。

-	Microsoft Word	Atlassian Confluence	Markdown with Git
良い点	簡単。さくっと書いてPDFで保存。書式も図も自由自在。	共同作業OK。慣れれば書式にもそれなりの自由度がある。PDF生成時に文書テンプレートを適用したり、文書の構造化やコードハイライト、各種マクロもGOOD。	全部テキスト。Gitで共同作業もバージョン管理もバッチリ。差分もバッチリ取れるので翻訳バージョンの追随が比較的簡単。
悪い点	バージョン管理や共同作業が大変。サイズが大きくなるに連れて、書式や言い回し、文書構造の不整合の面倒が見れなくなる。	バージョン管理があまり使いやすくない。複数文書への文言一括置換や翻訳バージョンの保持ができない（or 大変）。	Markdownにある程度の鍛錬が必要。書式の自由度は高くない。構造化が大変（？）。図式の貼り付けやPDF生成等、色々と外の仕組みが必要になる。

ただ、ぼんやりなので皆さんの意見や経験が聞きたくて質問しました。特に現状を今すぐ大きく変えようとしているわけではないのですが、今後何か大きな事を始めるorすすめるにあたって、Markdown with Gitにしてみたけども思いもよらない落とし穴があって後々やめとけばよかったと後悔したくないと思っているだけです。

よろしくお願いいたします。

※１　reStructuredTextは、PythonのプロジェクトにはいいのですがMarkdownのほうが汎用的かなぁと思って比較対象に入っていません。
※２　新たな比較対象を上げていただいてもOKです。
※３　頭の中にある「製品のドキュメント」のイメージは、「数～数十ページのアプリのユーザガイド」です。

Answer 1

自分はConfluenceとMarkdownどちらも使っています。

自分の業務を例にあげると、エンジニア以外にもドキュメントを書いてもらうことがあるのでそのような場合はConfluenceを選択することが多いです。

非エンジニアにMarkdownの書式を覚えてもらうことは大変かつPreviewツールを新たに導入してドキュメントを書いてもらうにしても少しハードルが高いためConfluenceという選択になります。

Markdown(またはRestructuredText)はエンジニアだけが書くような場合(サーバーでの作業手順書など)に時々用いられます。
ただ、Markdownでは表現力に欠ける部分もあるので多くはConfluence、RestructuredTextを選択するチームも多いです。

絶対的な正解といったものは無くそれぞれの事情にあったものを選ぶべきというのが持論です。

Comments

[YouheiSakurai]

ありがとうございます。なるほど、誰に(でも)書いてもらいたいという視点ではConfluenceが確かに良いですね。RestructuredTextの表現力は無知ゆえの盲点でした。RestructuredTextは少し勉強して見たいと思います。

[YouheiSakurai]

回答から「自分にとってはMarkdownが最適かもしれないが、他の人にとってはすとも限らない」という視点を得ることができました。ありがとうございました。

Answer 2

WordのメリットにPDFがある時点で、Word一択と思える程の影響力はあるでしょう。
Windowsで書かれたOfficeドキュメントは、Macで開いた瞬間フォントの違いから
オート改行→強制改行のコンボで盛大にレイアウト崩れする可能性があります、ご注意下さい。

Markdownは良くも悪くもHTMLを簡素な記述で表現する手段でしかありません。
その気になれば綺麗なCSSでラッピングして良い感じの画面を表示することは可能です。
PDF出力はコマンドラインツールでもなくはないですが、基本はChromeで表示してCtrl+Pの印刷機能を中継させて出力するのが楽でしょう。

手間暇がデメリットとして挙げられている以上、一回限りのスクリプトや環境を作るのにどれだけのコストで抑えられるかが分岐点になるでしょう。
私はそれなりにCSSを書くのが得意なのでHTML+CSSで履歴書を作ったりしましたが、熟練度によりますが大抵の場合は結構時間がかかると思います。
作ったスクリプトを同僚のデザイナー的な立場の人が実行出来るかと言った所も懸念点になりそうですね。

Atlassian Confluenceは利用したことがありませんが、
非エンジニアの方が多く触るケースでは良さそうですね。
生粋のエンジニア肌な人はMarkdownで書かせろと若干不満を覚えるかもしれません。

Comments

[YouheiSakurai]

なるほど。フォント不足によるレイアウト崩れも盲点でした。確かに一緒に作業する人の作業環境も考慮する必要がありますね。ありがとうございます。