130
Help us understand the problem. What are the problem?

posted at

updated at

Organization

文章が下手なワイが、技術記事を書くときにやっていること

文字での説明、むずい

「対面で説明するのは得意だけど、文章を分かりやすく書くのは、なんか難しい・・・」

そんなことってありませんか?
私はあります。

小学生のときの作文は、オカンに書かせていました。

担任の先生は、

先生「やめ太郎の作文、面白いから」
先生「オレ、楽しみにしてるんだよな〜!」

と言っていました。

コツが分からない

読みやすい説明文を書くコツが、イマイチ分かりません。
そのため、なんか読みにくい文章を書いてしまいます。

例えば、

動的型付き言語でのプログラミングに慣れきった人が静的型付き言語に学びの足を伸ばそうとしたときに考え方の違いから強い違和感を覚えてしまい学習がなかなか捗らない現象が起きることがあります。

↑こんな感じです。
めっちゃ読む気を奪ってくる文章ですよね。

なので、「分かりやすい文章の書き方」をネットで検索してみたこともあります。

どうやら、

  • 長い文を、複数の短い文に分割する
  • 無駄な表現を削る
  • 読点()を入れる
  • かっこ(「」)を使う
  • 対となる「主語」と「述語」を近づける
  • 対となる「修飾語」と「被修飾語」を近づける

↑こういうことをすれば読みやすくなるらしいです。

やってみた

さっきの文章を分かりやすくできるか、ネットで調べたコツを使って試してみました。

元の文章

動的型付き言語でのプログラミングに慣れきった人が静的型付き言語に学びの足を伸ばそうとしたときに考え方の違いから強い違和感を覚えてしまい学習がなかなか捗らない現象が起きることがあります。

直した文章

静的型付き言語を学ぼうとしたときに「学習がなかなか捗らない現象」が起きることがあります。
それは、動的型付き言語でのプログラミングに慣れきった人に起きがちです。
文化の違いから、強い違和感を覚えてしまうためです。

読みやすくはなったが、面倒くさい

元々の文より読みやすくなった気はしますが、頭が疲れました。

文章の「配置変換」みたいな行為が、脳のエネルギーを奪い尽くします。
できればやりたくありません。

もっと、対面で喋ってる時の感じでサクサク書きたいです。

なぜ対面では伝えやすいのか

なぜワイは、対面で説明することはできるのに、
分かりにくい文章を書いてしまうのでしょうか。

テキストにはなくて、対面での説明にはあるもの、それはなんでしょうか。

  • 喋りの「間」
  • 声の強弱
    • イントネーション
    • アクセント
  • ボディランゲージ

↑このあたりだと思います。

対面の場合だと、例えば・・・

「あのぉ」
「動的型付き言語でのプログラミングに慣れきった人がぁ」
「静的型付き言語に学びの足を伸ばそうとしたときにぃ」
「考え方の違いからぁ」
強い違和感を覚えてしまってぇ」
学習がなかなか捗らない現象が起きることがあるやないですかぁ」

↑こんな感じで、殆ど思いついたままに喋っても、文章より伝わりやすいんですよね。

その原因としては、

  • 喋りの「間」があるため、自動的に読点()が入った感じになる
  • 声でアクセントをつけられるため、強調したいワードが分かる

↑といったところだと思います。

あとは、途中で「伝わりましたか?」って聞いたりできますもんね。

やっぱ対面での説明、強いと思います。

もう、対面っぽく書いちゃえ

ということで私は、ほぼ全てのQiita記事を会話調で書いています。

ワイ「あのな」
ワイ「動的型付き言語でのプログラミングに慣れきった人がな」
ワイ「静的型付き言語に学びの足を伸ばそうとしたときにな」
ワイ「考え方の違いから、強い違和感を覚えてしもうてな」
ワイ「学習がなかなか捗らない現象が起きることがあんねん」

娘「そうなんだ」

↑こんな感じです。

声のアクセントを表現したい箇所には太字を使います。

これを徹底した結果、2020年に年間Contribution数で1位になれたので、一定の効果はあると思います。
(好き嫌いはあると思いますが・・・)

他にも

他にも、マークダウンの記法を活用することで「対面っぽさ」や「ボディランゲージっぽさ」を表現します。


ワイ「こないだ社長がな」

社長「社会人に大事なのは、この3つや!」
社長「よく聞け!」

ワイ「って言うてたんや」
ワイ「その3つというのは」

  • 報告
  • 連絡
  • 相談

ワイ「↑これなんや」


↑こんな感じです。
引用箇条書きなどを使います。

引用は「これは、誰かが言っていたことやで」ということを表現するときに使います。
箇条書きは「この三つは、同列に並ぶものやで」ということを表現するときに使います。

読者が疑問に思いそうな部分は・・・

特に説明が難しい部分や、誤解が生じやすい部分などは、

娘「パパ、それって〇〇ってこと?」

ワイ「いや、そうやなくて、△△なんや」

↑こんな感じで「読者が疑問に思いそうな部分」をあらかじめ説明したりします。
(これは@uhyoさんがワイ記法で書くときにやっていたので、逆輸入しました)

なんか楽に書ける

私は、プログラミングを勉強し始めてから5年間、一つも技術記事を書くことができませんでした。
でも「会話調でいっか」と考えだしてから、たくさん書けるようになりました。

まとめ

  • 分かりやすい文章を書くコツがあるらしい
  • しかしワイには難しかった
  • もう、対面の感じで書いてしまいたい

皆さんも、よかったらやってみてください。

〜おしまい〜

新しい記事も読んでみてくださいやで

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Sign upLogin
130
Help us understand the problem. What are the problem?