はじめに
アウトプットはした方が良いと言われて久しいですがじゃあ文書のアウトプットはどんな構造が良いのか？
という疑問が沸いたのでQiitaに投稿することを想定してまとめてみました。
この記事でできること
- Qiitaに記事を投稿するための軽い説明付きのテンプレートをコピペできます
- よい記事を書くための参考資料にアクセスできます
この記事の対象者
- Qiita投稿の初心者
- 技術系の記事を書いてみたいけど何から始めればいいか分からない人
- Qiita投稿のテンプレートをコピペして使いたい人
おおまかな流れ
この記事はだいたいこんな流れです。
- 読むべき参考資料
- テンプレートの構造とその説明
- コピー用テンプレート
【サンプル】 から始まる見出しが記事の構成とその説明です。
参考資料
記事の構成や何を書くべきかを教えてくれます。
【サンプル】技術記事のタイトル
1にも2にもタイトルが一番大事です。
タイトルは書き手が最も伝えたいことであるべきです。
簡潔かつ分かりやすく過不足ないタイトルを考えましょう。
- 最初にタイトルを考える
- 記事を書く
- もう一度タイトルを考える
と良いです。だいたいは最初に考えたタイトルから記事がずれたり、記事を書くことでタイトルがまとまるものです。
【 】(墨付き括弧)
【 】(墨付き括弧)を使って強調部を付けると関心を引きやすいです。
括弧内に何を入れるかは難しいですがQiitaではおおむね以下の使われ方をしています。(すべて架空の記事)
- 【言語やサービス】
- 例1.【Python】すぐにpytestで単体テストを実行するまでの手順
- 【言いたいこと】
- 例1.【必見】Objectはどこに消えた？
- 【前提】
- 例1.【個人開発】○○を○○できるサービスをリリースしました
- 例2.【初心者向け】Reactとはそもそも何なのか説明します
- 【続き物の番号】
- 例1.【2024年版】新入社員向け研修資料を公開します
- 例2.【環境構築編】Windows11でPythonを実行するまで
【前提】詳しいタイトル【言語やサービス】のように、複数を併用するパターンもあります。
【サンプル】はじめに
何についての記事なのか、誰に向けた記事なのかを簡単に説明しましょう。
【サンプル】この記事でわかる・できること
読んだら何がわかるようになるのか、何ができるようになるのかを書きましょう。
- わかること1
- わかること2
【サンプル】この記事の対象者
誰に向けた記事なのかを明確にすることで読者に選んでもらいましょう。
- 対象者1
- 対象者2
- 対象者3
【サンプル】動作環境・使用するツールや言語
環境を書くと分かりやすいです。
- OS バージョン
- 例 Windows11 23H2
- ツール
- 例 VSCode 1.86.2
- 言語
- 例 Python 3.12.2
- フレームワーク
- 例 flask 3.0.2
【サンプル】1.内容の大見出し(章)
章全体の要約や、何について書くのかをここに書きます。
章、節、項の番号については基本的には不要です。
ですが、長い記事、資料として使うことが分かっている場合、
番号を付けた方が取り回しが良いと考えています。
例えば、Pythonのpytestについての新人研修中
講師「『Session』の補足事項ですが…」
よりも
「『2.1.1 Session』の補足事項ですが…」
の方が伝わりやすいです。
【サンプル】1.1 内容の中見出し(節)
記事の主要な部分です。ここに思い思いの内容を書いていってください。
画像やGIFがあると分かりやすいです。
画像があるとUIが変わったとしても読者がアタリをつけて対応しやすくなります。
コードを記載する場合は必ずコードブロックを使いましょう。
コードブロックを使うときは言語指定もしてあげましょう。
【サンプル】1.1.1 内容の小見出し(項)
より詳細な内容を書いたり、事例を挙げたりするときに使います。
- 節の内容の列挙
- 節の補足事項
- 例外
見出しレベルは3つ以内にすることを推奨します。
これ以上たくさん使うと目次が汚くなり、読者が追いきれなくなってしまいます。
別の記事に分けることを考えた方がいいかもしれません。
【サンプル】参考資料
参考資料がないと読者に記事の正しさを1から調べさせることになります。
必ず書きましょう！
あと、なるべく一次情報を見ましょう。伝言ゲームと同じで参考になるたび変わっていきます。
【サンプル】おわりに・まとめ
どちらかを書きます。あってもなくても良いです。
よく使うMarkdown記法
QiitaにはMarkdownと共通のものと特有の記法があるので以下を参考に使いこなしてみてください。
テンプレート
テンプレート使用法
- テンプレートの右上にカーソルを近付けてください
- コピーボタンが出るのでクリックしてください
- Qiitaの下書きに貼り付けてください
- 記事を執筆！ 🎉
- コメントアウトされている部分(
<!--から-->までの間)を削除してください - 投稿！
コピー用テンプレート
<!--
## 技術記事のタイトル
最も伝えたいこと。
簡潔かつ分かりやすく過不足ないタイトルを考えましょう。
### 【 】(墨付き括弧)
- 【言語やサービス】
- 例1.【Python】すぐにpytestで単体テストを実行するまでの手順
- 【言いたいこと】
- 例1.【必見】Objectはどこに消えた？
- 【前提】
- 例1.【個人開発】○○を○○できるサービスをリリースしました
- 例2.【初心者向け】Reactとはそもそも何なのか説明します
- 【続き物の番号】
- 例1.【2024年版】新入社員向け研修資料を公開します
- 例2.【環境構築編】Windows11でPythonを実行するまで
【前提】詳しいタイトル【言語やサービス】のように、複数を併用するパターンもあります。
-->
## はじめに
<!--
何についての記事なのか、誰に向けた記事なのかを簡単に説明しましょう。
-->
### この記事でわかる・できること
<!--
読んだら何がわかるようになるのか、何ができるようになるのかを書きましょう。
-->
- わかること1
- わかること2
### この記事の対象者
<!--
誰に向けた記事なのかを明確にすることで読者に選んでもらいましょう。
-->
- 対象者1
- 対象者2
- 対象者3
### 動作環境・使用するツールや言語
<!--
誰に向けた記事なのかを明確にすることで読者に選んでもらいましょう。
環境を書くと分かりやすいです。
- OS バージョン
- 例 Windows11 23H2
- ツール
- 例 VSCode 1.86.2
- 言語
- 例 Python 3.12.2
- フレームワーク
- 例 flask 3.0.2
-->
- OS バージョン
- ツール バージョン
- 言語 バージョン
- フレームワーク バージョン
## 内容の大見出し(章)
<!--
章全体の要約や、何について書くのかをここに書きます。
記事が長い時や資料として作るときは番号を振ることをおすすめします。
章を増やすときは章から項までをコピーしてください。
-->
### 内容の中見出し(節)
<!--
記事の主要な部分です。ここに思い思いの内容を書いていってください。
画像やGIFがあると分かりやすいです。
画像があるとUIが変わったとしても読者がアタリをつけて対応しやすくなります。
コードを記載する場合は必ずコードブロックを使いましょう。
バッククオート3つで囲んでください。
```python:表示名
print('Hello World')
```
-->
#### 内容の小見出し(項)
<!--
より詳細な内容を書いたり、事例を挙げたりするときに使います。
- 節の内容の列挙
- 節の補足事項
- 例外
-->
## 参考資料
<!--
https://qiita.com
[リンク1](https://qiita.com)
-->
https://qiita.com
[リンク1](https://qiita.com)
## おわりに・まとめ
<!--
どちらかを書きます。あってもなくても良いです。
-->
コピー用テンプレート(コメント解説なし)
## はじめに
### この記事でわかる・できること
- わかること1
- わかること2
### この記事の対象者
- 対象者1
- 対象者2
- 対象者3
### 動作環境・使用するツールや言語
- OS バージョン
- ツール バージョン
- 言語 バージョン
- フレームワーク バージョン
## 内容の大見出し(章)
### 内容の中見出し(節)
#### 内容の小見出し(項)
## 参考資料
## おわりに・まとめ
おわりに
まずはテンプレートを使ったり書き方の記事を読みながら、軽い気持ちで書き始めて気軽に投稿するのが良いんじゃないかな～と思います。