質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

87.37%

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

解決済

回答 2

投稿 編集

  • 評価
  • クリップ 7
  • VIEW 7,737

score 5993

業務で色々な製品のドキュメントを作成したり翻訳したりしているのですが、ぼんやりと何某かの製品に関するドキュメントは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にしてみたけども思いもよらない落とし穴があって後々やめとけばよかったと後悔したくないと思っているだけです。

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

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

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 過去に投稿した質問と同じ内容の質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 2

checkベストアンサー

+3

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

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

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

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2018/01/31 23:16

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

    キャンセル

  • 2018/02/03 11:07

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

    キャンセル

+1

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

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

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

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

投稿

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2018/02/01 09:01

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

    キャンセル

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 87.37%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

関連した質問

同じタグがついた質問を見る