PyQの質問投稿フォームではMarkdown記法というテキストの書き方を使うことができるのをご存知でしょうか？
ソフトウェア開発に使うさまざまなツールがMarkdownに対応していて、ITエンジニアにとって欠かすことのできないものになっています。今回はITエンジニアがMarkdownを使うことのメリットとMarkdownの書き方を解説していきます。
Markdownとは？
見出しやリストでまとめられた構造的なドキュメントを作るための記法の一つです。まずはMarkdownで書いたテキストがどのようなものかを見てみましょう。
PyQチームのnao_yです。
PyQの質問投稿フォームでは**Markdownというテキストの書き方**を使うことができるのをご存知でしょうか？
ソフトウェア開発に使うさまざまなツールがMarkdownに対応していて、エンジニアにとって欠かすことのできないものになっています。
今回はエンジニアがMarkdownを使うことのメリットとMarkdownの書き方を解説していきます。
### Markdownとは？
. . .
実はPyQブログはMarkdownで書かれているのです。はてなブログがMarkdownで書かれた記事を変換して、ブラウザーで読めるHTMLにしています。
Markdownは.mdファイルとして通常のテキストエディターで編集することができます。PyCharmやAtomのようなプレビュー機能を持つエディターを使うとブラウザーでの見た目を確認しながら書くことができます。
エンジニアにとってのMarkdown
プロジェクトやプログラムの説明、更新履歴などのドキュメントを書くことが多いエンジニアにとってMarkdown記法は身近な存在です。Markdownのどのような点がエンジニアにとって嬉しいのでしょうか。
覚えやすい
Markdown記法はとても単純にできています。
例えば見出しレベルは # の数で決まっていますし、リストは - による箇条書きで表されます。他のページへのリンクも[PyQ](https://pyq.jp/)のように簡単に書くことができます。
編集するツールが限定されない
使い慣れたエディターで仕事をするITエンジニアも多くいます。Markdownはプログラムと同じように普通のテキストファイルとして扱えるため、ドキュメントを書くためだけにエディターを切り替える必要がありません。
プロジェクト管理ツールと相性がよい
GitHubやRedmineといったプロジェクト管理ツールがMarkdownに対応しています。これには以下のような利点があります。
- 普通のテキストファイルなのでプログラムと一緒にバージョン管理できる
- ブラウザーで読めるHTMLに変換され、読みやすいドキュメントになる
ドキュメントはプログラムの更新と併せて整備するので、同じ方法で管理できるのはとても重要です。
またGitHub上で直接、編集できるので微修正であればブラウザー上で行うこともあります。
可読性の高いドキュメントになる
見出しやリストで内容を整理することでドキュメントが読みやすくなります。
GitHub上でコードレビューをする際にもMarkdownを使っています。疑問点や指摘事項を簡潔にすることで、相手に伝わりやすくなります。結果として同じ箇所のレビュー回数が減り、仕事の効率化に繋がるのです。
Markdownの書き方
PyQの質問投稿フォームで使うことのできるMarkdown記法です。
一覧
Markdown
- The Beatles
- Oasis
- Arctic Monkeys
出力結果
- The Beatles
- Oasis
- Arctic Monkeys
見出し
Markdown
# 見出し
## 見出し2
出力結果
見出し
見出し2
コードブロック
Markdown
```python
def hello_world():
print('Hello world!')
hello_world()
```
出力結果
def hello_world(): print('Hello world!') hello_world()
言語を指定するコードブロックはGitHub Flavored Markdownという種類の記法です。Webサービスやエディターによっては正しく使うことができない場合があります。その場合は、言語を指定しない形式を使いましょう。
言語を指定しないコードブロックのMarkdown
```
print('Hello world!)
```
強調
Markdown
**The Zen of Python**
出力結果
The Zen of Python
引用
Markdown
> Beautiful is better than ugly.
出力結果
Beautiful is better than ugly.
リンク
Markdown
[PyQブログ](http://blog.pyq.jp/)
出力結果
まとめ
覚えやすい・ドキュメントの構造がわかりやすいの2点がMarkdownの強みです。
加えて、さまざまな開発ツールが対応している、書くエディターを選ばないことがエンジニアにとって嬉しい点です。
普段、Markdownでドキュメントを書く機会がないという方はPyQの質問投稿フォームで使い方を身につけていくのはどうでしょうか？
