これは何？
この記事では、Qiitaに限らず様々な場面でノウハウやTipsを共有するときに役立つノウハウ・Tipsを紹介します。記事を分かりやすくまとめ、課題の解決を望む人たちにダイレクトに届く記事を仕上げるための一助となれば幸いです。
表明しておくとよいこと
記事を書く上では何かしらのコンテンツがあるはずですが、そのコンテンツが一体何なのかを説明しておくと、読む人がスムーズに話題を理解できるようになります。
前提を明らかにしておく
共有したいノウハウやTipsがどんなときに役立つかという情報は非常に重要なものです。問題が再現する環境、そもそもどんな問題に対して取り組んだのか、そしてその問題が何故困るのか、ということを目のあたりにするからこそ、ノウハウやTipsが活きた技術として活用できるようになりますし、それらの前提が異なればノウハウやTipsも変わってくることでしょう。
特に小技紹介やお悩み解決のような記事では、どういうところに効果があるのかを述べておくと、ノウハウやTipsを活かしやすくなります。
この記事でも、まず最初にこれは何？としてどんなことに役立つかを明らかにしています。
ノウハウ・Tips の真髄はタイトルにする
ひとことで言うとどんなノウハウ・Tipsであるかの説明をタイトルにすることで、記事にどんなことが書いてあるかが理解しやすくなります。
また、何をどうしたのかがシンプルにまとまっているとより良いタイトルになるでしょう。
記事を読むことによって得られるメリットを明らかにする
どんな問題を、どのように解決したのかということも重要ですが、その結果どうなったのかというのもまた重要な情報です。あるいは、その記事を読むことで将来どうなることを目的とするのかということでも構いません。最終的なゴールがどこにあるかによって、ノウハウやTipsも変わってくるはずですから、そこを明らかにしておくことは、ノウハウやTipsを現場で活かす判断をする上で重要なことになります。
理由を明らかにする
どのような技術によってそのノウハウ・Tipsが支えられているのか、といったことや、なぜそのノウハウ・Tipsがうまく機能するのか、という点が明らかになることで、実際の場面で活用しようとした時の判断材料になります。もしかすると、微妙に前提条件や環境が異なっていたり、適用する理由として適当でない場面があるかもしれません。また、様々なトレードオフの関係にある物事を天秤に書けて、こういう理由・目的があるからA（またはB、Cなどの選択肢のうち一つ）を選択した、ということも有るでしょう。記事中に理由を表明しておくことで、どんな判断をするとよいのか、という一つの指針を作ることが出来るようになります。
Markdown 記法を活用する
文章を構成するのに必要な要素は上記に並べてみましたが、文章をうまく整理することで、読みやすい文章を書くことができます。
見出しを活用する
# 記号を重ねることで、見出しに階層を作ることが出来ます。この階層を活用して、文章を階層構造に分解し、順序だてて並べると、スラスラと読みやすい記事になります。
また、見出しのタイトルはその見出しで解説している内容の要約になっていると、見出しを目次にしたときに、文章全体がどのようなことを話しているかがひと目で分かりやすくなります。
リンクは言葉に貼る
URL をリストするだけの場合を除いて、引用や参考リンクを張る場合には、URL のみを貼り付けるのではなく、ある程度の手短な言葉や引用元・参考リンク先のタイトルを用いてその言葉にリンクを張るようにします。このようにすることで、リンク先に何が有るかが分かりやすくなります。
その意味では、「ここ」や「こちら」といった言葉にリンクを張るのは避けたほうが良いかもしれません。コードを参照する場合でも、どのコードのどのあたりかをリンクとして用いると分かりやすくなりますね。
長文記事には TL;DR なセクションを置く
2~3ステップくらいの手短なインストラクションで、何をどうすればどうなるのかを説明するだけのセクションがあると、読む人の理解が深まりやすくなるでしょう。その場合、以後の見出しとTL;DRのセクションの順番は一致させておくことが望ましいですね。
まとめを用意する
最終的に何が大事だったのかをまとめましょう。最初に表明した概要と同じでも構いません。
まとめ
ノウハウやTipsを共有する上では
- 大事な部分の要約をタイトルにする
- 前提条件をはっきり表明する
- 何故そのノウハウやTipsが役だったのか、どうしてその判断をしたのか、理由を述べる
- 実践した結果どうなったのかを明らかにする
- (可能ならば)他のやり方はあるか、あるとしたら何故それをしなかったのか理由を挙げてみる
が文章を構成する上で大事な要素になります。
また、これらをまとめる上では
- 見出しの構成をうまく分解して、階層構造を作る
- リンクを言葉に貼って参照先を分かりやすくする
- (必要ならば)TL;DR なセクションを用意して全体像を把握しやすくする
- まとめを置いて結局何が言いたかったのかを整理する
ことを意識すると、より読みやすい記事に仕上がることでしょう。
参考リンク
いい記事を書くためのガイドライン - Qiita::Support