contributionsが100を超えたので、作業メモ/備忘録/まとめ系記事のテンプレートを整備してみる

はじめに

概要

• 自分はQiitaで作業メモ/備忘録/まとめ系の記事を書くことが多いです。
• ほぼ自分専用のつもりで記事を書いていました。
  • いつの間にかContributionsが100を超えていたのをきっかけに、Qiitaに残す以上は人から見られることも意識するべきとおもい、テンプレを作ろうと思いました。
    • ちなみに、自分の記事は1記事あたり2-5 LGTMレベルで記事の質は高くないですｗ
• プログラムは1ヶ月前に書いた自分のコードは人のコードになると言いますが、記事も同じで、1ヶ月前の自分の記事は意外と読みにくいものです。
  • 備忘録といえどもテンプレートを整備して、時間が経って読み返しても読みやすいような記事になりやすいように、テンプレートを整理してみました。

対象読者

• Qiitaの記事の構造に迷っている方
• 備忘録、自分用のメモをよく残す方

関連記事

• Qiitaで良い記事を書く技術
• Markdown記法 チートシート

スタート(前提条件)

• 基本的になし。Qiitaのアカウントを持っていることぐらいです

ゴール(達成できること)

• 備忘録系の記事の構造が少し良くなるかもしれません

スコープ外(ふれないもの)

• 日本語的なわかりやすさ、てにおは、文章構造などの改善には触れません

開発環境

• OS/ブラウザには依存しません

---

本編

全体像/結論

• 自分の約50の記事を読み返して、構造化したところ後述のテンプレートに落ち着きました
  • 個人的には、トップレベルを「はじめに」「本編」「補足」とするのが収まりがよくなりました。
• 本稿の記事は、このテンプレートに従っています

本稿で使われているテンプレート

• コピペ用にテンプレートとその項目で何を書くかの箇条書きをセットにしています

テンプレート

# はじめに
## 概要
* 全体像/結論/TL;DR/概要相当
* きっかけ/モチベーション/何がしたいのか

## 対象読者
* どんな人に役に立つのか

## 関連記事
* 自身の兄弟記事
* 参考文献の先行記事

## スタート(前提条件)
* 本稿の内容を実施する前にしておくこと

## ゴール(達成できること)
* これを読むと何を達成できるのか

## スコープ外(ふれないもの)
* 対象外とするもの

## 開発環境
* OS/ツール/サービスのバージョンなど(再現できるように)

---

# 本編
## 全体像/結論
* 全体をを先に伝えてわかりやすくする

<!-- 必要な分繰り返し ここから -->
## ○○
* step/partなど大分類別に記載　構造化して書く

### イメージ
* スクリーンショットやイメージ図を書く

<!-- 必要な分繰り返し ここまで -->

## 所感
* 思ったこと、考えたこと

---

# 補足
## 備考
* 注意事項やうまくいかなかったことなど書く

## 参考文献
*  公式URLや外部記事

## 追記
* yyyy/mm/dd 追記した情報を記載

強調したい部分の工夫

Qiitaではhtmlも一部使えるため、下記のような強調を入れることも良いかと思います。

• 赤文字
• 太文字
• アンダーバー

テンプレート

<font color='red'>重要な部分には赤文字を</font>。
<b>重要な部分は太文字に</b>。
<ins>アンダーバー</ins>

所感

• 記事の構造もですが、日本的なわかりやすさなどにも気を配らないとだめですね(当たり前ですがw)
  • 他の方の記事を読むと、難しい漢字は"ひらく"(漢字ではなくひらがなにする)べきなどもあり勉強になりました

---

補足

備考

• 伝える記事の内容によって、構造が変わるのは自然かと思います
  • 使えそうな部分をご自身のスタイルに合わせてカスタマイズして取り入れて貰えれば幸いです

参考文献

• 公式：良い記事を書くためのガイドライン公式

追記

• 2020/10/30 初稿