わざわざ「メンター」と書いてあるということは……？https://t.co/hSIXC8Z55I
— やぎちゃん (@ygkn35034) November 2, 2017
(期待)
— うーぴょん@毎週日曜浮上するうさぎ (@sasurai_usagi3) November 2, 2017
ということで、はじめましてまたはこんにちは！ やぎちゃんです！
今年も Life is Tech Members Advent Calendar をすることができて嬉しいです！
一日目はもっと記事書いてくれる人が増えるように、という想いも込めて、技術記事初心者の方のために、「技術記事のすゝめ」という内容で書いていきます。
メンバーの皆さんも、メンターの皆さんも、それ以外の方々も最終日までどうかよろしくお願いします！
なぜ記事を書くか
伝える
記事を書く一番の理由はずばり「伝える」ことだと思います。
その相手は見ず知らずの他人だったり、未来の自分自身かもしれません。
僕も何回か自分が書いた記事に助けられることがあります。
その他に、記事を書く上でのメリットはその他にもあります。
現状の知識の整理
まとまった記事を書くにはその書くことに対する知識と、その整理が必要です。
もちろん書く前の段階から完璧に理解できてるにこしたことはありませんが、記事を書く上で頭の中が整理できたり、知らないことや分からないことを発見することもあります。
承認欲求
もちろん記事を書いてバズったら嬉しいというのも人によって、多い少ないの違いはあれど、あると思います。
準備
どこで書く？
記事を書くにはいろんな手段があります。書く内容や目的に合わせて選ぶといいでしょう。
Qiita
まずはこの記事を公開しているここ、Qiitaです。
Qiitaを使うメリットは、
- 技術ごとに記事がまとまる（タグ機能）
- ブログより手軽に始められる（新しく開設する手間がない）
- Markdownや絵文字など基本的な機能はサポートしてる
- 作者のネームバリューが低くても拡散力がある（SEO、ランキング、Bot etc…）（結構重要）
でしょう。
逆にデメリットは
- デザインや機能を凝れない
- 「いいね、ストック」問題
- エディタや、通知などが痒いところに微妙に手が届かない所がある
でしょうか。
僕はQiitaのエディタに関してはDropbox Paperで記事を書いて、Qiitaで投稿しています。
ブログ
ここではBloggerやはてなブログなどのブログサービスやWordPressなどのCMSを使ったサイトのことをブログと言います。
ブログサービスについては（軽くググって例を挙げるを諦めるほどには）様々な種類があります。
そのような中で、技術系のブログは（主観ですが）はてなブログにて開設されている物が多いような気がします。
他のブログサービスと同じようにある程度のカスタマイズ性があるのに加え、Markdownが使えたりシンタックスハイライトができたりといった点が重宝されているようです。
その他の方法
上記以外にも、Twitterの共同創業者が作ったMediumというブログとTwitterの間のようなサービスや、コード共有サービスである GitHub Gist で記事を書いてる人も見かけます。
内容を決める
まず「伝えたいこと」をきめます。これがあやふやだったりすると何が言いたいのかよくわからない記事になってしまいます。
箇条書きで書いてみたりしてもいいかもしれません。また、いざ書いてみてあとで書きながらまとめていくのもアリです（当然あとで細かい修正は必要ですが）。
書いてみよう
まとまったら、エディタを開いて記事を書いていきます。
見出し（枠組み）を作る
まずは見出しを書きましょう。
この時点で大見出し（<h1>や#）だけか小見出し（<h2>や##）まで書くかはお好みで。
僕は記事の内容と気分によって変わります。
１つの見出しと見出しの間、つまり章や節で言いたいことは１つにしましょう。
見出しはぱっとみてその章や節の内容がわかるように書くといいです。
サービスによっては（例えばQiitaなど）目次を自動的に作ってくれるものもあり、それを見ただけで内容がわかるようになります。
Q Accelerator（Qiita の便利機能を集めた Chrome 拡張機能）にあるような記事のテンプレートを使うことはオススメです。自作のテンプレートを作っている方もいるようです。
さらに書き進める
見出しができたらその間を埋めて完成です。
ここまできたら筆が進むのではないでしょうか。
さて全部書き終えたら完成！ 早速公開だ！
……といきたいところですが、まだ最後にやることがあります。
文章のチェック
最後に書いた文のチェック、いわゆる校閲をします。
チェックといえどあなどってはいけません。むしろここからが本番です。
以下のことに気をつけます。
前提条件の確認
技術記事は「伝える」ために書きます。
読者のレベル（初/中/上級者など）や環境（ソフトウェアのバージョンなど）「誰に伝えるか」の前提条件を明確にしておきます。
そして必ず記事のどこかに入れておきます。
文体の統一
「です・ます口調」と「だ・である口調」が混じってませんか？
僕は地の文では「です・ます」を、コード内のコメントや箇条書きの中などでは「だ・である」を使っています。
正式名称の使用
スペルミスや大文字/小文字、スペースの有無はあっていますか？
e.g.
OK JavaScript
NG Java Script, javascript, javaScript etc…
読みやすく
たとえばこんな風にある程度長い文章を改行も句読点も入れずにだらだらと続けるととても読みにくいので音読して息継ぎをするタイミングで読点を入れ文と文はできるだけ分けて基本的には一文で改行を入れましょう。またリストも活用するといいです。
↓ 読みやすくすると
たとえばこんな風に、ある程度長い文章を、改行も句読点も入れずにだらだらと続けると、とても読みにくいです。
- 音読して息継ぎをするタイミングで読点を入れる
- 文と文はできるだけ分ける
- 基本的には一文で改行を入れる
などをするといいです。
参考資料の記述
記事を書く上で参考にした他の記事やドキュメントを書いておきましょう。
また、似たような記事が存在するけど何らかの事情（その記事の情報が古い、間違っている etc…）で新たに書かなければいけない場合はその記事にリンクを貼ると閲覧者が便利です。
記事のメンテも忘れずに
これは書いた記事が増えてくると大変ですが、内容が古くなった記事は、「この記事の内容は古いです！」と追記するだけでもいいので更新しておくとベターです。
Tips
Markdown
Qiitaやはてなブログ、GistなどではMarkdownというマークアップ言語で記事を書けます。
これは、HTMLをより簡潔に書けるようにしたものです。
検索したらいろいろなマークアップがありますが、一般的な記事でよく使うのは「見出し」「リスト」「太字」「コード」くらいです。
覚えとくと便利なマークアップ
<kbd>
Ctrl+C
とすることで、キーボードショートカットを表すことができます
<details><summary></summary></details>
要約
詳細詳細詳細詳細詳細詳細
のように長い文章を折りたたむことができます。
最後に
明日の記事は……まだ埋まってないようです。
Life is Tech ! Members Advent Calendar 2017、まだまだ記事は募集中ですのでどしどしご参加ください！
テーマはなんでも結構です！
P.S.
技術的な文章を書くための1歩、2歩、3歩 - Qiita
書き終わってから気づいたのですがこの記事もいい記事だったので紹介させていただきます。