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記法が用意しているのが「文書をよくするための体裁だけ」だからです．

https://developers.google.com/tech-writing/one?hl=ja
の左帯にある目次の下から二つめ
https://developers.google.com/tech-writing/one/markdown?hl=ja
です．その真ん中あたりにある
https://www.markdowntutorial.com
を開けてください．

これが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

表の中の要素は右寄せやセンタリングができる．
でも，表自体やキャプションをセンタリングする手立てはなさそう．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の引用

意外とむずいですね．

     ```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タグは？