技術文章について考えてみたい
mactkg
この記事が話題になっているが、この記事の末尾が本当に言いたかったテーマなのかもしれないと思った。
初学者向けの技術ブログ記事の場合、簡略化のためわざと書いている可能性もあります。しかし、僕はそれがいいこととはあまり思えません。初学者が今回の記事のように自力で応用してみようとしたときに思い通りに動作せず困惑させることになるからです。
それよりかは多少難易度が上がったり説明文が多くなったとしても、適切な API の紹介をすべきだと思います。
これは、技術文書をどう書くか？という話に感じたので、スクラップを書いてみたい。
mactkg技術文書というか、他人に読んでもらう文章を書くときに気をつけることかもしれないが、大事なことはなんだろうか。思いつく限り、リストアップしてみたい。
- 伝えたいことをはっきりさせて、一文でまとめる。
- 箇条書き、表、図などをうまく活用して、わかりやすくする。
- 文章の目的をはっきりさせる。誰がいつ、なんのための目的で読むことを想定しているのか。この文章がある理由は何か。
- 事実と意見を分ける。
- 事実を書く場合、ソースを意識する。
（ちなみに、スクラップはブログみたいなものだし、↑には当てはまらないものもあると思います）
mactkg初学者向けの技術ブログ記事の場合、簡略化のためわざと書いている可能性もあります。しかし、僕はそれがいいこととはあまり思えません。初学者が今回の記事のように自力で応用してみようとしたときに思い通りに動作せず困惑させることになるからです。
これは難しい話だと思う。逐一エッジケースを話すよりは、先に進んでしまってもいいと思う。自分が大事だなと思うは、ドキュメントやソースなど、一次情報を意識すること。初学者にもここを意識してもらえれば、ハマったりしないと思う。誰かのブログは調べるきっかけにはとてもありがたいのだが、バージョンが古かったり、対処療法的で、根本的な解決に至っていないものもある。なぜそれでうまく動くのか、一次情報にありつければ、変にハマることはない。
と考えると、さっきの箇条書きには、一次情報を意識する。ということを入れるべきかもしれない。
mactkgじっさい、自分zennに書いた記事でも、一次情報は意識して書いている。
詳しくはドキュメントを参照してください。
Next.js 9.4以降からは、
.envや.env.developmentなどといったファイルでprocess.envの値を書き換えられるようになっています。
React Dev Tools使用時は
__REACT_DEVTOOLS_GLOBAL_HOOK__が定義されるようなので、これを使って判別してみても面白いかもしれません。時間がある時に試してみたいと思います。
こうしてみると、一次情報というのは色々なレベルがあることもわかる。ドキュメントもあるし、ソースコードは最高の一次情報だな。それが動いているわけだから。
mactkgということで、技術文書について考えてみた。このようなことについて考えている人はたくさんいると思うので、資料へのポインタを貼ってみたいと思う。
GoogleがTechnical Writingのコース。ちなみに私は受けてません。
hyukiさんの数学文章作法は、昔読んでよかった気がします。 (アフェリエイトリンクになっています)
hyukiさんの数学文章作法を調べるためにGoogleで検索していたら、次のようなページも見つけた。これは参考になりそう。
Zenn自体が、良い文章を書く方法についてまとめてくれても素敵なのかもしれない。
mactkg皆さんも何か意見があればください。
januswelご紹介されている Google の Technical Writing は英語ですが、日本語にも通じる非常にいい資料です。
次のふたつの URL を読めばいいので、機械翻訳を使ってしまえば数時間で読めると思います。
また、日本語での書き方については理科系の作文技術が挙げられがちですが、より噛み砕いてわかりやすい、次の本がオススメです。
januswelきっかけとなっている記事は良記事ではあるのですが、おっしゃるとおり主張がわかりづらいことと、タイトルが強い言葉なのでさらに主張がわかりづらくなっている点は僕も感じました
こういった議論を提起してくださってありがとうございます