Introduction

How do you handle documentation at work? If you're a Qiita user, you might frequently use Markdown. At my workplace, the norm was to write documents in Word. Recently, we've switched to using Markdown, and I'd like to share what steps we took in this process.

Note: This article does not intend to criticize Microsoft Word or claim Markdown is superior. The workplace described is a software engineering department dealing with technical documents. Please read with this context in mind.

Strategy 1: Taking Meeting Minutes in Markdown

Initially, our workplace didn't have a habit of recording meeting minutes. I started taking notes on my own and distributing them post-meeting, which was well-received, leading me to continue as the meeting scribe. I initially used plain text files but later switched to Markdown. When distributing these notes, I included:

The file extension is .md, but it’s just a text file. You can view it with your preferred text editor. However, if you use a Markdown-compatible editor, it’s easier to read. Feel free to try it.

Strategy 2: Creating Allies

Thanks to my efforts with the meeting minutes, a colleague became interested in Markdown. We pledged to promote its usage together. Now, they are even more enthusiastic than I am.

Strategy 3: Finding a User-Friendly Editor

Initially, I recommended various extensions for editors like Atom, VSCode, and Eclipse to colleagues. However, they voiced concerns such as:

• Editing and viewing split-screen was cumbersome


• Vertical monitors made viewing difficult


• Styles messed up when exporting to PDF/HTML


• Difficulty remembering syntax for creating tables or inserting images

To solve these issues, we found the perfect editor—Typora. Here's a helpful article about it: Why Doesn't Everyone Use Typora for Markdown Writing?.

When opened in Typora, the Markdown file looks like this:

Strategy 4: Conducting a Markdown Workshop

After gradually using Markdown for various documents such as README files over a year, all members acknowledged its existence. We conducted a workshop to introduce Markdown. It was well-received with positive comments like:

• "It's lighter than Word."


• "Useful for PCs without Office installed."


• "We can deliver PDFs to clients after conversion."

The workshop successfully integrated Markdown into our documentation culture. I'm glad we persevered!

Bonus

Recently, we adopted HackMD, which allows collaborative editing for meeting notes.

Here's a useful article about HackMD: HackMD: A Revolutionary and User-Friendly Markdown Editor. The colleague who first joined me in promoting Markdown set up the HackMD environment, greatly enhancing our note-taking efficiency.

Note: The goal was to reduce lengthy document creation times in Word, due to manual syntax highlighting, page adjusting, and change logging. Markdown's features like automatic code block coloring, lack of page concepts, and version control with Git made it an appealing alternative. However, for rich document expressions or external documentation, we still use Word and include change logs when necessary.