はじめに
ドキュメントって皆さんどうしていますか？
Qiitaで記事を書いている方なら、Markdownを普段から使う人も多いと思います。
私の職場では、「Wordでドキュメントを書く」という習慣がありました。
最近、「Markdownで書く」というのを定着させることができましたので、その過程で何をやったのかを共有したいと思います。
2018/11/02 追記
本記事に、Microsoft Wordを批判する意図はございません。
WordよりもMarkdownが優れているという主張をするつもりもございません。
それと、後出しで恐縮ですが、本記事に登場する職場とは、ソフトウェアエンジニアがメインの部署です。
ドキュメントというのも、技術系資料です。
その前提でお読みください。
誤解があるといけないので追記いたしました。
（追記終わり）
やったこと１：議事録をMarkdownで取った
私の職場では会議の議事録を取る習慣がそもそもありませんでした。
そこで、私の方で勝手に議事録を作り、それを会議後に配ることにしました。
それなりに好評で、継続して私が議事録の書記をすることになりました。
最初はただのtxtファイルで議事録を書いていましたが、途中からMarkdownで作るようにしました。
配る際に、
拡張子はmdですが、中身はただのテキストファイルなので、お好きなテキストエディタでご覧ください。
ただ、Markdownに対応したエディタで閲覧すると、より見やすくなりますので、ご興味のある方はお試しください。
というメッセージを添えるようにしました。
テキストエディタ(CotEditor)で開くとこんな感じで、
Markdownエディタ(VSCode)で開くとこんな感じです。
やったこと２：仲間を作った
議事録をがんばったおかげで、同僚の一人がMarkdownに興味を持ったので、「一緒にMarkdownを定着させましょう」と誓い合いましたｗ
今では私よりも、この方の方が意欲的です。
やったこと３：使いやすいエディタを探した
最初の頃は、Atom, VSCode, Eclipse等の拡張機能を、同僚に紹介していました。しかし、
- 編集と閲覧の2画面に分割されて見にくい
- 縦長モニタだと更に見ずらい
- PDFやHTMLへエクスポートすると、スタイルが崩れる
- 表の作成や図の挿入のような作業は文法を覚えられない。WordみたいにGUIで作りたい。
といった不満の声が挙がっていました。
これらを解決できるエディタを探したところ、ぴったりのものが見つかりました。
Typoraです。こちらの記事が参考になります。
どうしてみんなMarkdown書くときTypora使わないの?
先ほどのMarkdownをTyporaで開くと、こんな感じです。
やったこと４：Markdownの勉強会を実施した
議事録以外にも、readmeとかでMarkdownを使ってみたり、1年程かけて徐々にMarkdownを使う場所を増やしていき、メンバー全員がMarkdownの存在を認識した頃に、Markdownの勉強会を実施しました。
大きな反発はなく、むしろ好意的な意見が多かったです。同僚からは以下のようなコメントをいただけました。
- Wordよりも動作が軽くていいね
- Officeが入っていないPCでも使えていいね
- PDFに変換すれば、お客様に納品もできるし、使いやすいね
この勉強会がきっかけになって、ドキュメントをMarkdownで書く文化が職場に浸透しました。
諦めずにがんばってきて良かったです！
おまけ
最近は同時編集可能なHackMDを導入して、議事録もそこで取るようにしています。
HackMDはこちらの記事が参考になります。
HackMDってMarkdownEditorが革新的で使いやすい
最初に仲間になった同僚が、HackMDの環境を作ってくれました。これによって議事録作業が大幅に効率化されました。
2018/11/02 追記２： Markdownを定着させたかった目的
Markdownを定着させたい目的は何？という意見をいただいたので追記します。説明不足で申し訳ありません。
Wordでドキュメントを書いていた頃は、ドキュメントの作成時間が長いという課題がありました。原因は３つくらいありました。
- サンプルコードの色付けを手動でやる習慣があった。
- 違和感のない改ページになるように、文章量を調整する習慣があった。
- ドキュメントの変更履歴を、ドキュメント内で手動で書く習慣があった。
Markdownの場合、以下のような特徴があるので、これらの課題を解決できそうでした。
- コードブロック記法で自動的に色付けしてくれる。
- ページという概念がないので、改ページもない。
- mdファイルをGitでバージョン管理すれば、それが変更履歴になる。
この辺りが、Markdown導入のモチベーションでした。
ただ、Markdownでは表現しきれないリッチなドキュメントは、今でもWordで書いていますし、対外的なドキュメントでは、ドキュメント内に変更履歴もつけています。
2019/10/28 追記
同じ職場で、今度は Swagger を導入してみました。興味があればぜひご覧ください。
Wordな職場にSwaggerを定着させようとして失敗したけど結局定着した話