Help us understand the problem. What is going on with this article?

Wordな職場にMarkdownを定着させるためにやった4つのこと

はじめに

ドキュメントって皆さんどうしていますか?
Qiitaで記事を書いている方なら、Markdownを普段から使う人も多いと思います。

私の職場では、「Wordでドキュメントを書く」という習慣がありました。

最近、「Markdownで書く」というのを定着させることができましたので、その過程で何をやったのかを共有したいと思います。
image.png

2018/11/02 追記

本記事に、Microsoft Wordを批判する意図はございません。
WordよりもMarkdownが優れているという主張をするつもりもございません。

それと、後出しで恐縮ですが、本記事に登場する職場とは、ソフトウェアエンジニアがメインの部署です。
ドキュメントというのも、技術系資料です。
その前提でお読みください。

誤解があるといけないので追記いたしました。
(追記終わり)

やったこと1:議事録をMarkdownで取った

私の職場では会議の議事録を取る習慣がそもそもありませんでした。

そこで、私の方で勝手に議事録を作り、それを会議後に配ることにしました。
それなりに好評で、継続して私が議事録の書記をすることになりました。

最初はただのtxtファイルで議事録を書いていましたが、途中からMarkdownで作るようにしました。

配る際に、

拡張子はmdですが、中身はただのテキストファイルなので、お好きなテキストエディタでご覧ください。
ただ、Markdownに対応したエディタで閲覧すると、より見やすくなりますので、ご興味のある方はお試しください。

というメッセージを添えるようにしました。

テキストエディタ(CotEditor)で開くとこんな感じで、
スクリーンショット 2018-11-01 14.13.17.png
Markdownエディタ(VSCode)で開くとこんな感じです。
スクリーンショット 2018-11-01 14.11.32.png

やったこと2:仲間を作った

image.png
議事録をがんばったおかげで、同僚の一人がMarkdownに興味を持ったので、「一緒にMarkdownを定着させましょう」と誓い合いましたw

今では私よりも、この方の方が意欲的です。

やったこと3:使いやすいエディタを探した

最初の頃は、Atom, VSCode, Eclipse等の拡張機能を、同僚に紹介していました。しかし、

  • 編集と閲覧の2画面に分割されて見にくい
  • 縦長モニタだと更に見ずらい
  • PDFやHTMLへエクスポートすると、スタイルが崩れる
  • 表の作成や図の挿入のような作業は文法を覚えられない。WordみたいにGUIで作りたい。

といった不満の声が挙がっていました。
これらを解決できるエディタを探したところ、ぴったりのものが見つかりました。

Typoraです。こちらの記事が参考になります。
どうしてみんなMarkdown書くときTypora使わないの?

先ほどのMarkdownをTyporaで開くと、こんな感じです。
スクリーンショット 2018-11-01 14.18.28.png

やったこと4:Markdownの勉強会を実施した

image.png
議事録以外にも、readmeとかでMarkdownを使ってみたり、1年程かけて徐々にMarkdownを使う場所を増やしていき、メンバー全員がMarkdownの存在を認識した頃に、Markdownの勉強会を実施しました。

大きな反発はなく、むしろ好意的な意見が多かったです。同僚からは以下のようなコメントをいただけました。

  • Wordよりも動作が軽くていいね
  • Officeが入っていないPCでも使えていいね
  • PDFに変換すれば、お客様に納品もできるし、使いやすいね

この勉強会がきっかけになって、ドキュメントをMarkdownで書く文化が職場に浸透しました。

諦めずにがんばってきて良かったです!

おまけ

最近は同時編集可能なHackMDを導入して、議事録もそこで取るようにしています。
image.png
HackMDはこちらの記事が参考になります。
HackMDってMarkdownEditorが革新的で使いやすい

最初に仲間になった同僚が、HackMDの環境を作ってくれました。これによって議事録作業が大幅に効率化されました。

2018/11/02 追記2: Markdownを定着させたかった目的

Markdownを定着させたい目的は何?という意見をいただいたので追記します。説明不足で申し訳ありません。

Wordでドキュメントを書いていた頃は、ドキュメントの作成時間が長いという課題がありました。原因は3つくらいありました。

  • サンプルコードの色付けを手動でやる習慣があった。
  • 違和感のない改ページになるように、文章量を調整する習慣があった。
  • ドキュメントの変更履歴を、ドキュメント内で手動で書く習慣があった。

Markdownの場合、以下のような特徴があるので、これらの課題を解決できそうでした。

  • コードブロック記法で自動的に色付けしてくれる。
  • ページという概念がないので、改ページもない。
  • mdファイルをGitでバージョン管理すれば、それが変更履歴になる。

この辺りが、Markdown導入のモチベーションでした。

ただ、Markdownでは表現しきれないリッチなドキュメントは、今でもWordで書いていますし、対外的なドキュメントでは、ドキュメント内に変更履歴もつけています。

2019/10/28 追記

同じ職場で、今度は Swagger を導入してみました。興味があればぜひご覧ください。
Wordな職場にSwaggerを定着させようとして失敗したけど結局定着した話

segur
Unity認定プログラマー。VR学会認定技術者。xRエンジニア。ガジェットが大好きなギーク。毎日バックパックPCを背負ってる。 色んなコンピュータ言語に触れるのが好き。 開発経験言語(触った順)HSP/BASIC/C/C++/Verilog/PHP/Java/JavaScript/C#/Python/ShaderLab/Ruby/Go/TypeScript
https://segurvita.github.io/
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした