記事の書きかた
技術記事の類型について,よい記事があったので書きとめる。それをもとに,記事のはじめにその性質をどのように示すかについて考える。
技術記事は大きく「学習」「解説」「提案」の3つに分類でき,それらを明らかにしておくのがよいという記事に出会った。
- https://zenn.dev/uhyo/articles/technical-articles
- 鈴木僚太(うひょ)
- 技術記事の3類型: 初心者による技術記事執筆のすすめ
- Zenn
- 参照 2024-12-05
この記事にある分類は直観的でよい。数学でも似たようなことが言えるだろう。
筆者の考えでは、技術記事は比喩的に「学習ノート」・「教科書」・「論文」の3類型に分類されます。主な分類基準は記事の目的・記事が生む価値は何かです。
このように「この記事はどのような意図で書かれたのか」ということを記事中で明らかにすることは、読み手に記事の意図を正しく理解してもらうために重要です。そして実は、これは初心者に限らずどんなレベルの記事においても基本的かつ重要なことです。「対象読者を明記する」といったことも記事の意図を伝える手段として優れています。ですから、初心者のうちから「記事の意図を読み手に伝える」ことを練習しておくと有利です。
さらに,discussion についていた次の言葉選びもよい。
教科書=>解釈ノート、解説ノート
論文=>提案ノート
という感じでしょうかね。(Nobkz)
幽霊新聞の記事は,すべて個人的なメモ書きである。 そうはいいながら,自らがいつか見返すにあたっても,信頼性・新規性を判断するためにはこれらのいずれであるかが書かれているべきだろう。
一方,高校数学調律研究室の記事は,誰かに使ってもらうことも考えて書いている。 そして,自分の考えを整理するためにMathlogにもアカウントを作った。 また,職場では作業マニュアルのようなものを教員向け・生徒向けに書くこともある。 これらについては,読者へ向けてこれらのいずれであるかが書かれているべきだろう。
そのために,自らが書くあらゆる記事について,それが学習・解説(解釈)・提案のいずれにあたるのかを明らかにしておきたい。
まず,はっきりと3つの類型を立てて,タグやカテゴリで明らかにすることが思いあたる。しかし,2つ以上の要素を含むもの,なかなか分けがたいものはどうしても生じるだろう。前者は,この記事がその例である。記事の3類型は学習ないし解説であり,この部分で自らの記事にどう落とし込むかは提案に近い。後者は,概要記事が例のひとつになるだろう。したがって,この手は早々と行き詰まる。
そこで,記事のはじめに自然な文としてこれらを示すことにしたい。日本語としてどれを示しているのかが伝わるようにし,そのうえで概要記事などで細かく定義しておくのである。この方法であれば,2つ以上の要素を重ねてはじめることも,いずれも入れずに始めることも無理なくできるだろう。
話が変わるが,その他の文書を書くことにあかる記事をいくつか書きとめる。
- https://blog.riywo.com/2021/01/how-to-write-high-quality-technical-doc/
- Ryosuke Iwanaga
- 質の高い技術文書を書く方法
- As a Futurist…
- 参照 2024-12-05
- https://www.hyuki.com/writing/writing
- 結城浩
- 文章を書く心がけ
- 結城浩の公式サイト
- 参照 2024-12-05
- https://qiita.com/freddi_/items/fe8e878187f315d80d87
- 秋勇紀
- 読み手をイライラさせない技術記事などを書くために最低限守ったほうがいいこと
- Qiita
- 参照 2024-12-10