Markdownを社内に布教したい、というモチベーションからMarkdownを勧める理由をまとめたもの。
同じようなことを考える方へ、周囲への説得材料になると嬉しい。
1. Markdownを勧める理由
1-1. 圧倒的理由
全人類がマークダウンを学習すべき理由｜情報デザイン力を鍛えよう
Markdownとは (日本語Markdownユーザー会) をMarkdownで引用する。
Markdown（マークダウン）は、**文章の書き方**です。
デジタル文書を活用する方法として考案されました。特徴は、
- 手軽に文章構造を明示できること
- 簡単で、覚えやすいこと
- 読み書きに特別なアプリを必要としないこと
- それでいて、対応アプリを使えば快適に読み書きできること
などです。
Markdownはジョン・グルーバー（John Gruber）によって2004年に開発され、
最初は [Daring Fireball: Markdown](http://daringfireball.net/projects/markdown/) で公開されました。
その後、多くの開発者の手を経ながら発展してきました。
つまりシンプル。かつ、使うだけで分かりやすいドキュメント作成を自動的に意識できる。
情報デザイン＝あらゆる情報をわかりやすくすること。
マークダウンとは、情報構造がわかりやすい記法 である。
1-2. 変換しやすい
シンプルということは、いかようにも加工しやすいということだ。
校正、推敲、スライド作成、その他フォーマットへの変換はいくらでも可能である。
Markdownファイル校正手順 - 実務編
マニュアルの校正作業ツライのでVSCodeにtextlint入れた - 文章推敲ツール色々
Chrome拡張などで文書校正のtextlintをもっと簡単に使う - textlint editor
1分でも早く仕事を終わらせるためにVSCodeにできること
爆速でスライドを作る！Markdownからスライドを作れる「Marp」
結局Markdownでプレゼン資料ってどれで作ると良いのよ？と思ったときの選択肢
[VSCode]MarkdownをPDFで出力してレポートを書く
こんなツールもある。
1-3. Gitでの版管理と相性が良い
Git と組み合わせればさらに強力になる。
- ソースコードと同様、commitの履歴から、原稿がどう変わっていったのかわかる。
- どれが原稿の最新版なのか、ファイル名に日付を入れなくてもわかる。
- リバートできる。
- 誰が修正したのかわかる。
具体例をあげるなら、
ユーザーヒアリング1-1_山田最新版_Final★完了★20210222.docx
ユーザーヒアリング1-1山田田中最新版_Final★完了★20210212.docx
ユーザーヒアリング1-1_山田田中中田最新版_Final★完了★20210225.docx
...のような地獄からの開放。
- 変更点に関して、Git上で議論できる。
- 修正案を検討しやすくなる。
つまりGitの強みをすべて享受できる。
世の中の小説作家と編集者は今すぐ Word や G Suite を窓から投げ捨てて Git と GitHub の使い方を覚えるべきだ、いわんや開発者をや、だ。強調する。圧倒的に「自分にとって便利になる」のだ。
2. 反論とその答え
2-1. 記法が難しい
大丈夫。Markdown記法 チートシート を読もう。
あるいは読まなくても、
## これがタイトル
- これとか
* これとかで箇条書き
だけで良いんじゃないだろうかとも思う。それだけで伝わるように考えるほうが重要。
Markdownは頭の中の情報整理を助けるメソッド (冒頭で「情報デザイン」と書いた) だと思ったほうが良い。
「マークダウン書く時なんか崩れちゃうんだよな」ポイントをなくす - Qiita 等も参考。
2-2. 伝えたいことを強調できない、色を付けたい
Word とか ナントカDocument じゃダメなのか。一人で執筆するだけなら好きな道具で良い。
執筆するだけなら、何を使っても問題ない、しかし個人開発でない限りおよそプロジェクトは複数人だろう。だからテキストでシンプルに、Markdownなのだ。
テキストファイルのバージョン管理は Git を使いましょう。あなたが楽になります。
テキストファイルの共同編集作業は GitHub を使いましょう。みんなが楽になります。
以上引用: 文章に関わる全ての人のための Git & GitHub 入門 1-1「Git と GitHub を使うメリット」
表を使いたい場合こんなツールもあるが敢えて表を挿入したくなった場合は表で表現する必要あるのかな？と自問自答してもいいと思う。
2-3. Spreadsheet のほうが共同編集できる
これは一理あると思っています。特にオンライン会議上でああだこうだ言いながら共同編集する方法はかなり有効。すべての場合において強制したいとは思わないのです。
しかしそうやって会議を行った結論は最後にサマリして配布するだろうから、そういう時には検討しても良いんじゃないだろうか。その資料を更に他で利用できるかもしれない。
2-4. すでに社内のたくさんの文書がMarkdown以外で書かれている
これもわかるけど、ここまでに書いたことに少しでもメリットを感じて頂けるなら変えていってもいいと思いませんか。変換ツールがあります。
Pandoc
- word文書(docx)ファイルをmarkdown形式に変換する
- Googleドキュメントから効率的にMarkdown作成【Docs to Markdown】
-
多様なフォーマットに対応！ドキュメント変換ツールPandocを知ろう
- 例:
pandoc input.docx -s -o output.md - 例:
pandoc wiki.txt -f mediawiki -t markdown_github -o wiki.mdなどという感じで使える。
- 例:
- https://pandoc-doc-ja.readthedocs.io/ja/latest/users-guide.html
コマンド例:
pandoc input.docx -s -o output.md
pandoc input.docx -t markdown-raw_html-native_divs-native_spans -o output.md
Mediawiki to Markdown
PDFからテキスト抽出
3. Markdownで使いやすいエディタ
ここまで書いてもまだ訝しいと思われると思う。これを使うと良いというのを書いておく。
Typora
どうしてみんなMarkdown書くときTypora使わないの?
強力なMarkdownエディタ「Typora」に今更入門
StackEdit
Markdownテキストでシーケンス図とフローチャートを描く
超高機能マークダウンエディタ「StackEdit」の Welcome Document を和訳してみた
VSCode
Hackmd
テーブル
その他
補足
あとはこれだけある過去記事でも眺めつつ
https://qiita.com/tags/markdown
Wordな職場にMarkdownを定着させるためにやった４つのこと をリスペクトして書いたのでこれで少しでも仲間が増えたら嬉しいなーーー。
やったこと１：議事録をMarkdownで取った
やったこと２：仲間を作った
やったこと３：使いやすいエディタを探した
やったこと４：Markdownの勉強会を実施した
Excel方眼紙で手順書作るのやめ隊 - AWS/GitHub/CircleCI/mkdocs でドキュメント管理-
行政文書をマークダウン化しよう！ところでマークダウンって何？｜METI-DX 経済産業省情報プロジェクト室
コメント: https://b.hatena.ne.jp/entry/s/metidx-gov.note.jp/n/n2bd18b23dba3
行政文章はMarkdownで管理できるか｜Hal Seki｜note
コメント: https://b.hatena.ne.jp/entry/s/note.com/hal_sk/n/n916a422caafd
等
以上、少しでも幸せな開発ドキュメント生活の参考になればさいわいです。