Markdownはテクニカルライティングの基本を強制する

Googleのtechnical writing講座

Qiitaの元記事¹はわずか2日で1000を超えるLGTM(Looks Good To Me)を獲得したことからもわかる通り，プログラマの琴線に触れる語句が散りばめられています．ここでは少し違った観点からgoogleの元ネタを吟味したいと思います．

その重要性

googleのコース²では，technical writingに必要なごく当たり前のことを当たり前に並べているだけです．でも，それぞれがtechnical writingの実践で，素晴らしいサンプルになっています．特に

1. 簡明な英語で表現
2. 目次で内容が一目瞭然
3. 所要時間で分量が判別
4. 綺麗な体裁で提示

されていることです．その中でもこの講義で強調したいのは，最後におまけみたいについているMarkdown記法です³．qiitaの記事を用いたmemoの作成法で紹介した通り，あるいはいくつかの提出課題に対して指摘した通り，Markdown記法を使うだけで文書はよくなります．

なぜかというと，Markdown記法が用意しているのが「文書をよくするための体裁だけ」だからです．

Technical Writing One introduction
の左帯にある目次の下から二つめ
Markdown (variable)
です．その真ん中あたりにある
https://www.markdowntutorial.com
を開けてください．

これがMarkdownの基本スタンスです．新入生のために，和訳しておきましょう．

No	Engilsh	日本語
1	Markdown is a way to write content for the web.	マークダウンはウェブの中身を書く手法の一つです．
2	It’s written in what people like to call “plaintext”, which is exactly the sort of text you’re used to writing and seeing.	これは"平文"と呼ばれる，あなたが書いたり見たりしてきたテキストで書かれています．
3	Plaintext is just the regular alphabet, with a few familiar symbols, like asterisks ( * ) and backticks ( ` ).	"平文"てのは普通のアルファベットと，アステリスク( * )とかバックコート( ` )なんかのお馴染みの記号でできています．
4	Unlike cumbersome word processing applications, text written in Markdown can be easily shared between computers, mobile phones, and people.	重たいワープロソフトと違って，Markdownで書かれたテキストはコンピュータや，スマホ，そして人々のあいだで簡単に共有できます．
5	It’s quickly becoming the writing standard for academics, scientists, writers, and many more.	Markdownは大学人，研究者，物書きなど多くの人にとって，急速に書くことの標準となりつつあります．
6	Websites like GitHub and reddit use Markdown to style their comments.	Githubやredditというサイトでは，コメントを整形するのにMarkdownを使っています．
7	Formatting text in Markdown has a very gentle learning curve.	Markdownを使ったテキスト整形は，ゆる〜〜く学習が進みます．
8	It doesn’t do anything fancy like change the font size, color, or type.	フォントサイズや色やタイプを変えるようなおしゃれな発想はいりません．
9	All you have control over is the display of the text—stuff like making things bold, creating headers, and organizing lists.	あなたが調整すべきはテキストをどう見せるか，すなわちボルド(太字)にしたり，ヘッダーを作ったり，リストを構築することだけです．
10	If you have ten minutes, you can learn Markdown!	10分あれば，Markdownは習得できます！

この文章こそがMarkdownを使うことの意義をまとめています．特に，No.8,9あたりです．ぜひ，10分かけてこれをやってみてください．英語の自信にもなりますよ．

Markdown記法のヒント

見出し

# 見出し
# 見出し 1
## 見出し 2
### 見出し 3

文字飾り

**強調**
_italic_
[リンク](http://...)

リスト

- リスト 1
- リスト 2
    - リスト 2-1
1. 番号付きリスト 1
2. 番号付きリスト 2
3. 番号付きリスト 3
- [ ] チェックボックス 1
- [ ] チェックボックス 2
- [x] チェックボックス 3

table

     **Table:cpation**
| hogehogehoge | hagehagehage |
|---:|:---:|
|haho| hoho|

     Table:cpation

hogehogehoge	hagehagehage
haho	hoho

表の中の要素は右寄せやセンタリングができる．
でも，表自体やキャプションをセンタリングする手立てはなさそう．html直打ちしてみたが，スタイルはいじれないから．

• 試してダメだったhtml記法
  上記の例は， で少しそれらしくしている．

図なんかはテーブルの中に入れると綺麗になる．

| fig-url |
| caption |

数式

latex(mathjax)と同じ．

文中では，$ e = \frac{1}{2}mv^2 $という感じ．
中心寄せで別行仕立てでは，
$$
\int_0^{1} f(x) dx
$$

文中では，$ e = \frac{1}{2}mv^2 $という感じ．
中心寄せで別行仕立てでは，
$$
\int_0^{1} f(x) dx
$$

markdownの引用

意外とむずいですね．

sample.md

     ```python
     //コメント
     print("hoge")
     ```

でcodeをcolorizeしてくれます．

//コメント
print("hoge")

普通の引用(block quote)

latexなんかのquoteです．

    > hogehoge
    > hogehage

hogehoge
hogehage

です．メールの引用からのメタファ．たくさん文章があるときは，改行せずに頭に'>'をつけておけば全部引用になります．

hogehogehogehogehogehogehogehogehogehogehoge
hogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehoge
hogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehogehoge

qiitaでは改行してもいいようです．実環境で試してください．

中身の表示

どうやっているのだろうというqiita記事のmarkdownを直接見たければ，urlに'.md'をつければ見えます．

• Qiita Markdown 書き方 まとめ
  後で気がついたんですが，右上の機能ボタンのプルダウンにも「Markdownで本文をみる」がありますね．

注釈

文献の引用などには注釈機能を使います．[^cite1]とかして，それを
[^cite1]: hogeと受けます．注釈内容を置く場所は，本文中でも末尾でもいいですが，表示されるのは末尾．:の後のスペースに注意．

• https://qiita.com/Qiita/items/c686397e4a0f4f11683d

ドキュメント内のリンク

  [chap6 tkinter 優秀記事](#chap6-tkinter-優秀記事)
  ## chap6 tkinter 優秀記事

なんてね．

Details - 折りたたみ

<details><summary>謎の言葉</summary>あの久楽山脈さん菩提</details>

謎の言葉

あの久楽山脈さん菩提

• Markdown記法 チートシート

Definition型

<dl>
  <dt>リンゴ</dt>
  <dd>赤いフルーツ</dd>
  <dt>オレンジ</dt>
  <dd>橙色のフルーツ</dd>
</dl>

comment

<!-- this is a comment. -->

スライド

純粋なテクニカルライティングの話題からは外れますが，qiitaには簡単なスライド機能が用意されています．

• スライドモード
  これも**必要最低限の機能だけ(デザインより中身)**を提供してくれています．

qiita特有記法

• Qiitaで使えるHTMLタグは？

---

• source :: ~/Desktop/lecture_22s/CompAInfo/c4_markdown.md

1. Qiitaの元記事 ↩

2. Technical Writing(Google Developers) ↩

3. Markdown(variable) 「オマケみたいと書いたのはvariableのせいなんですが，その意図は演習が外部リンクになっていて所要時間が不定だからでしょうね．読むことを任意という意図ではなさそう」って書いてましたが，本文にはoptional(おまけ)ってついてました．申し訳ない． ↩