知識を整理する記事を書くときに考えていることを整理してみる
投稿日: 2021年9月22日 更新日: 2021年9月22日
カテゴリ: 雑記
概要
知識を整理することを目的とした記事を書くときの考え方を整理してみます。
ざっくり要約
記事を書くとき、どんな知識を提供することが目的か、ゴールを定めるのが重要です。
そして、ゴールへ至るまでの道筋を伝わりやすくまとめるには、より正確で・より解釈しやすい形とするための資料集めが欠かせません。
集めた資料から、いかに自分の言葉で知識を書き出せるかが、記事を書く上でのポイントとなります。
目次
前置き
いくつか記事を書いてはいますが、毎回書き方を忘れてしまっています。ある程度の大枠・手順が頭にあるので、雰囲気で書けてはいます。
ですが、やはりたくさんの記事を質を高めながら書けるようになりたいので、再現性が欲しいところです。
そこで、より効率よく記事を書くため、大まかな手順を整理してみます。
また、知識を整理する記事を書くのはそれなりに大変なので、書くことでどういうメリットがあるのか忘れないよう書き出しておきたいです。
構成
最初に、いつも記事で書いている節の要素を書き出していきます。 これにより、記事の大枠を定めることができます。
続いて、枠の中へ知識を書き出すための手順を整理することで、より効率良く記事を完成させるための考え方を確立していきます。
記事の大枠
目的・アプローチはある程度共通しているので、テンプレート化しておきたいところです。
しかし、ただ枠組みをつくるだけでは、なぜそれが必要なのか見えづらくなってしまいます。その節をなんのために書くのか、言語化することで利便性を見出していきたいと思います。
その前に全体像を掴んでおくために構成をざっくりと箇条書きでまとめておきます。
- 概要
- ゴール
- 用語整理
- ゴールを目指すためのステップ
- まとめ
各要素の詳細を順に見ていきます。
要素-概要
記事の中身を一言で表現した、いわゆるサブタイトルに相当する要素を最初に書きます。
例えば、タイトルが「正規表現を学んでみる」だったとしましょう。
概要部分には、一例として、grepコマンドを利用してサンプルファイルからパターンを抽出する旨を書くことにします。
このように、記事の中で何をやるかを知ることで、大まかな全容を見ることができます。
目次からも全体像は追えますが、やはり一言で言語化されたものがあると、理解も進むはずです。
要素-ゴール
記事を読むことでどのような知識が得られるのかを記述します。
知識を整理した記事は、なんらかの知識を提供することを目的としています。そうなると、読む前に気になるのは、記事からどんな知識が手に入るかということです。
書き手の視点では、ゴールで示した知識を読者に提供できているか、という指標を持つことができます。
読み手の視点では、得られる知識から読むべきか否か取捨選択することができます。更に、記事を読むとき、理解の目標として、提示されたゴールを満たせたかどうか、指標とすることができます。
目指すべき場所が定まっていると、記事を書く/読むときにも迷子になりにくいはずです。
要素-用語整理
記事で扱う技術と、関連する用語のざっくりとした定義を書き出します。
技術を理解し、使いこなす上で、用語の定義を押さえておくことは重要です。
技術を学んでいて「なんか分からないな〜」と思うときは、関連する用語を言語化するのにつまずいていることが多いです。
大事なところなので、もう少し掘り下げてみましょう。
例えば、正規表現の「前方参照」という用語を理解するには、assertion, ゼロ幅, 文字クラスが何を表しているか
言語化できなければなりません。もちろん、関連する用語を組み合わせ、前方参照それ自体も言語化しなければ、理解に至ることはできません。
なんとなく使うだけであればサンプルの見よう見真似でも多少はカバーできます。
ですが、文字クラスとの使い分け・否定前方参照など、複雑なことを扱うようになると、表面的な理解では歯が立たなくなってしまいます。
正規表現に限らず、複雑な技術は前提の積み重ねで実現されています。
難しさ・複雑さが分かる状態へ持っていくには、前提となる概念を自身の言葉で表現し、腹落ちさせることが求められます。ですので、技術を理解していく上では、言葉の定義を掘り下げていくことがとても重要となります。
少し長くなってしまいましたが、言葉の定義を明確にしていくことは、「分からない」を解決する上でとても有効なアプローチです。
理解を促すためにも、重要な用語は定義を一箇所に固めておくとよいでしょう。
要素-ゴールを目指すステップの書き出し
以降の構成は記事によって異なりますが、大筋は同じです。 書くべきことは、ゴールへたどり着くための道のりです。いかに道のりを歩きやすく整備できるかが記事の質に大きく関わってくるのです。
再び正規表現を例に考えてみましょう。
grepコマンドでファイルから特定の表現を抜き出せるようになることをゴールに見据えます。ただ正規表現の構文を並べただけでは、一次情報の焼き増しとなってしまいます。記事で必要なのは、理解に至るまでに感じた課題を、自分のアプローチで解決する方法を提供することです。
私の場合は、正規表現を理解していく上で、「記法の意味が頭に入らない・サクッと試せるサンプルがあったらもっと早く理解できたのに」という課題を感じていました。
これを解決する上で、「前方参照などの複雑な概念は、複数の文献を参照しながら、仕組みを言語化する・記法ごとに例題を用意し、grepコマンドで簡単に試せるようにする」アプローチをとりました。
あとは、記法を難易度順に並べ、簡単なものから少しずつ例題を解いていき、徐々に複雑なものへ立ち向かう過程を言語化していけば、(きっと)素敵な記事ができあがります。
一度解決した課題を時間を掛けて言語化するのは面倒に思えます。
しかし、知識は定着するまでに何度も忘れてしまいます。忘れてしまったときは、大体同じような課題で行き詰まることになるので、解決の過程が大いに役立つことになります。
これは万人受けする記事にはならないかもしれませんが、自分自身・そして、自分に近い前提を持つ人にはとても有益なものとなるはずです。対象読者を広げるために、提供する前提知識・本文で提供する周辺知識を増やそうとすると、慣れるまでは完成する前に力尽きてしまいます。
記事を書くのはとても労力の掛かることですので、「ここまでは書きたい!!」というところを見定めていくのも大事かもしれません。
要素-まとめ
概要やゴールといくつか重なる部分がありますが、記事でどんな知識を得るために何をやってきたか、まとめておきます。まとめの節は、ゴールへきちんとたどり着くことができたか振り返るための役割を持っています。
書いたときは、ゴールと本文の繋がり・読んだときは得た知識とゴールの繋がりを振り返ることで、得られたものを評価します。
手順
大枠から、枠の中に何を書けば良いかざっくりと決めることができました。
しかし、これだけでは、どう書くか考えるときに詰まってしまいます。より具体的には、「なんか節の間の繋がりがいまいちな気がする・そもそも言語化に詰まる・スピードが全然出ない」といった問題に直面することになります。
記事を書くときに悩む時間を減らせるよう、実際に書くときのアプローチも整理しておきましょう。
手順-枠決め-何を書くか
最初にざっくりと章立てをしておきます。 マークダウンならば、ヘッダ部分のみを書いておきます。ゴールを見据えておくことで、後の手順で迷うこともなくなるはずです。
ゴールへの道程を分解していくのは詰まりやすいところなので、もし詰まってしまったら、一旦先に進んでしまうのも手です。
後から見直してみると、補いたいところ・削りたいところが見えやすくなります。
手順-材料集め
材料集めは、記事を書く上で最も大事なところです。
いい材料が揃わなければ、記事を書く途中で手が止まるか、ゴールまでの過程が曖昧になってしまいます。
材料とは
材料の指すものを明らかにしておきましょう。材料は、記事を書く上で役立つと思うものは、なんでも当てはまります。というと掴みどころが無くなってしまいますね。具体例を挙げてみましょう。
シェルスクリプトの記事を書きたいときは、「書籍・公式ドキュメント・自分が実際に試した一連のファイル・詰まったときに参照した文献」が材料となります。
材料がそろっていると、記事の中で「簡単なサンプルを示したい・構文の説明がしたい」など、書きたいものがあるところで役立てることができます。
情報の取捨選択
知識を整理する記事を書くことは、自分が得た情報のうち、重要だと思ったものを選び取ることだと言い換えられます。選択する過程で、画像を言語化することもあるかもしれませんし、文章からイメージ図にすることもあるかもしれません。
選び取った結果は、自分の表現で構成された、自分にとって最も理解しやすいものとなるはずです。
やや抽象的な話となりましたが、集めた材料は、そのまま自分の表現できることの上限となります。表現力を高めるために、この過程でありったけの材料をかき集めておきましょう。
手順-下書き
材料が集まったら、一気に書き殴っていきます。途中でこの表現はどうなんだろう、とか、ちょっと繋がりがいまいちかも...といった、いわゆる詰まる要素が湧き上がってくるはずです。
ですが、立ち止まると多くの場合、動き出すまでに苦労することになってしまいます。
ですので、下書きの過程は、多少不格好でも、とにかく書き進めるのが大事です。とはいえ、ゴールへ進めているかは、最低限見失わないようにしなければなりません。
書く途中で進もうにも進めなくなったときは、大抵、材料が不足しているので、材料集めに戻ります。一番しんどいところですが、ここを乗り越えれば完成に大きく近づけることができます。
手順-推敲
書き上げた段階ではなく、日が変わったら・一節書き上げたらなど、途中の段階でも少しずつ見直していきます。見直すときは、表現と内容を分けて考えると、読むときに混乱しにくくなるかもしれません。
推敲は知識に出会う機会を増やせるので、知識の定着にとても有効です。繰り返し読み直して、記事・理解の質を高めていきたいところです。
100%を目指そうとすると、心が折れてしまうので、ある程度のところで打ち止めにしましょう。この辺りの基準は個人の性格にもよるところなので、自分の納得できる基準を見出すのが大事です。
私は、「表現に概ね納得できた・読み終わったときにゴールへ近づけた感じがした」ときを完成と決めるようにしています。
おわりに
こう書き出してみると、やはり記事を書くのはとても大変なことですね。労力は掛かるけれど、なんか良いらしいから書くか、というだけでは燃え尽きてしまいます。
ですので、最後に、なぜこんな苦労をしてまで記事を書くのか、言語化しておこうと思います。
理解を深めるため
プログラマとして力をつけるには、コードを書くことが重要だとよく言われます。
ですが、コードを書くときに行き詰まったことは、余裕が無ければあまり深くは調べず、目の前の課題を解決できる程度で通り過ぎてしまいます。すると、何度も調べる割には、なんだかいまいち理解できていない、もやもやする状態に陥ってしまいます。
これを脱却する上で、記事を書くのはとても有効です。記事として公開するには、なんとなくコードが書ける/やりたいことが実現できる程度の知識量では全く足りません。自分の言葉で表現するため、あちこちに材料を集めまわったりと、さまざまな試行錯誤が必要となります。
時間の掛かることではありますが、記事を書き終えたあとは、なんだか理解が浅いなぁと思う気持ちも、きっと薄れているはずです。
効率よく知識を入れ直すため
頑張って書いた記事も、1週間も過ぎれば頭から抜け落ちてしまいます。せっかく書いても忘れてしまうのなら、なんだか意味の無いような気がしてきます。
ですが、記事は自分の欲しい知識を得るのに最も効率のよい形をしています。つまり、忘れてしまっても自分の書いたものを繰り返し読み返すことで、より早く、より深い知識を身につけることができるのです。
得た知識を俯瞰するため
日々知識を増やしても、目に見える形でなければ、知識が本当に増えているのか不安になります。
そんなとき、書いてきた記事を見返せば、きっと自信となるはずです。
まとめ
思ったより長くなってしまいました。
個人的なメモではありますが、記事を書くときに少しでも参考になれば幸いです。
記事はGitHubでも公開しています。間違い・よりよい書き方などございましたらIssueやPRを頂けるとうれしいです。
Author:
a-pompom: