初めに
記事を投稿する前にこのレビューリストを見てセルフレビューしよう！
Markdownでコピーして、各自のVScodeでプレビューすると、チェックボックスも使えます。Githubにも載せています。
Markdownの書き方がなっていない、スタイルがめちゃくちゃな記事をよく見かけます。特にフロントエンジニアなどはよく見られるので、気をつけてください。
Markdownレビューリスト
タイトル
- 妥当なタイトルをつける (たとえば、初心者向けなのか?プロフェッショナル向けなのか?などターゲットを意識する)
- 具体的で簡潔なタイトル
- 強調したい内容は基本的に【】でくくる。(【3分で習得】など)
タグ
- 不要なタグはつけない (無関係なタグなど)
- 正しいタグをつける (〇Python ✕ python)
- ターゲットがなるべく多いタグをつける (〇 Python(77315))
本文
スタイル
-
見出しは
###レベル3まで → ネストが多い場合は記事を分ける - styleの統一 (path名はbold, メソッド名はイタリックで統一するなど)
- 長文より短文の方が見やすい。ポエム にしない。
- 読みやすさを確認 (パッと見てみて強調してる箇所が目に入ってくるかなど。)
-
特に強調したい箇所は
<font color='red'>色をつけるという手もあります</font>で色をつける - 段落構成(限定公開で全体表示したときに右サイドバーの目次で確認。)
-
見出しレベルが連続している。
#の次に###を使わない。 -
強調で
#を使わない - 上から下へと順番に読める
- 改行、空白、スペルミスのチェック
- MarkdownのLinterでチェックしている
-
記事内リンクは
(hoge)[#hoge]でつける - ライブラリ名やツール名を使う際は、HPなどのリンクを追加する。(e.g. Golang)
- 上記以外の外部のリンクは基本的にまとめて参考文献へ。(飛んだら戻ってこなくなる可能性がある)
図表
ソースコード
- 正しいシンタックスハイライトをつける
- コードが記事通りコピペして動作する
-
コードが長いときは
<details><summary>title</summary><div>contents</div></details>で折りたたむ。 - コードに記載されているファイル名が正しいのか。(カレントディレクトリを統一する)
-
Terminalの場合は
shell-session:terminalを付ける(terminalやconsoleもできるが、互換性を考えて、shell-sessionに統一。プロンプト付けない場合 はbatchなど) -
Terminalのプロンプトを
$に統一。(%はシンタックスハイライトがつかない) -
プレーンテキストのシンタックスハイライトは何もつけない。(○
:hoge.txt×text:hoge.txt) - フロントなどCodePenを使った結果とコードが見やすいなら利用する
参考文献、注釈
- 注釈記法 を利用する
-
注釈記法が面倒な場合は、
[title](url)で最後にまとめておく