良い記事を書く為には
タイトル
タイトルを見ただけで記事の中身が想像できるようする
目次を書く
目次を読むだけで全体の構成が分かり、読みたい個所も探しやすくなる
環境や前提条件を説明
ソフトウェアのバージョンは何か、記事中のコードを実行するためにはどんな手順が必要かを書いておくと、自分の環境に当てはまるかどうかを後から読む人が判断できるため
余計なことは書かない
分かりやすく、やたらと長くしないこと
悪い例
普通の例
良い例
文章構成
文章構成がしっかりしていないと、分かりづらい文章になる
1、おっ(見出し)
2、何々(概要)
3、へぇ~(意見)
4、なるほど(証拠)
5、わかった(結論)
概要を伝える
概要を一言伝えておくことで、読者に読む準備ができる
概要を伝えなければ、一体何を伝えているのか不明
要点は箇条書き
伝えたいことが3点以上あるときや、話をまとめるときなどに便利
説明文の書き方は、2パターンある。
説明文の使い分けは、説明文の長さが(例えば5行以上になるか)で判断
事例を挙げて説明する
(例)この〇〇を使うことによって、XXになりました。
重要なことは重要と書く
「ここは重要な箇所ですよ」と読者に伝える必要がある
Markdown記法を使う
Markdown を使えば、他の人に書いている内容が明確に伝わる
ソースコードは、一部だけうめこまないようにする
よりも下の方がわかりやすい
引用元や参考元へのリンクを書く
他のwebページから文章を引用したらそのページへのリンクを貼り付ける
記事の内容を理解する助けになるページがあれば親切
参考にした記事
https://qiita.com/ucan-lab/items/17c806973e69792ada99
https://qiita.com/HiromuMasuda0228/items/a71dea7ef4d77a30b118
Qitaでいいねの記事の人
文章構成の多くはこのような感じでした。
・タイトル
・はじめに(概要)
どのような方々読んでもらいたいか、
どのような前提条件をしっかりと記載している。
なぜ、このような記事を書いた経緯も軽く説明してる。
サイドメニューバーのようなものも右側にある。
・目次
・AAA
・BBB
・CCC
・AAA
ソースコードなどサンプル画像
実行
結果
メリットなど
・BBB
ソースコードなどサンプル画像
実行
結果
メリットなど
・CCC
ソースコードなどサンプル画像
結果
メリットなど
・まとめ
・参考・引用