どこにでもいる凡人プログラマや未経験プログラマから頭一つ抜きん出たい
複数人をまとめるリーダープログラマやSEになりたい
そのためには、ひたすらコードを書いているだけで良いでしょうか？
もちろんコーディングの経験を積むことは欠かせません。
しかし優れたプログラマになるためには、文章力も重要だと考えています。
実際、リーダープログラマやSEになると、設計書や仕様書の作成など、文章を書く機会は多くなります。
質の高い文章を書き、信頼されるエンジニアを目指しましょう。
文章力の重要性
プログラマはコード以上に「文章」を書いている
プログラマの仕事は「コードを書く」だけではありません。
- 設計書の作成
- 仕様書の作成
- Slackやメールでのやり取り
- 日々の作業報告や進捗報告
少し挙げただけでも「コードを書く」以外の作業が多くあることが分かります。
他にはQiitaやブログで技術情報の発信をしている方もいらっしゃるかもしれませんね。
これらの作業においては、コードを書く時とは異なり、技術や目的を正しく伝える「文章力」が重要となります。
当然、プログラマであれば良いコードを追求すると思います。
しかし「文章を書く」ということに関してはいかがでしょうか？
振り返ってみると、コードを書く以上の時間を文章を書くことに費やしている人も多いと思います。
そのような「文章を書く」ということ、重要でないはずがありません。
しかし、自身の書く文章について、真剣に考えたことのある方は少ないのではないでしょうか？
- 設計書に曖昧な記述があったり矛盾があったりしては、コードに落とし込むことができません。
- 仕様が明確でない関数やライブラリは、不安で使えません。
- スムーズなやり取りには、目的を簡潔に伝える能力が欠かせません。
製品の価値を左右するのはコードではなく「文章」
文章で利用者の心を掴む
APIやライブラリ、フレームワークなどを利用するとなると、1度は公式ドキュメントに目を通すと思います。
しかしその際、ドキュメントが不親切だったり、解説が理解しづらかったりしたら、どう感じますか？
そんなツール、使う気を無くしてしまいますよね。
理解しやすいコードや移植性の高いコードを書くことは、もちろん重要です。
しかし、利用者がまず初めに見るのは、コードではありません。
説明文やドキュメントです。
ここで利用者を引きつける文章を書けるか否かで、利用してもらえるかどうかが決まります。
せっかく良いソフトウェアを作成しても、誰の目にも止まらなければ意味がありません。
優れた文章はコードの価値を高める
価値の高いコードとは、どのようなコードでしょうか？
- バグが少ない
- 移植性が高い
このようなコードを書くためには、実は文章力が鍵となります。
より具体的には、優れたコメントや仕様書を書く能力、そのための優れた設計書を書く能力が重要となります。
他人のコードを読む場合を考えてみましょう。
例えば、コメントに関数の仕様が適切に書かれていれば、デバッグを円滑に行うことができます。
再利用もしやすいですよね。
一方、コメントや仕様書など、コードの理解を助ける文章が一切無い場合。
そんなコード、解読する気にもなりませんよね。
関数名や変数名が唯一の助けですが、コメントさえも書かないプログラマの命名なんて当てになりません。
ちなみに、関数の仕様を簡潔に説明できるということは、その関数が簡潔であることの証明にもなります。
仮に「この関数は○○して△△する関数です」と説明が複雑になってしまうようであれば、それは関数としての単位を見直す必要があります。
この場合であれば、「○○する関数」と「△△する関数」に分けるべきです。
なお、コメントや仕様書を書くことは、個人制作の私的なプログラムでも同様です。
過去に自身で作ったプログラムのアルゴリズムが意味不明なんて経験ありませんか？
未来の自分はもはや他人です。
せっかく作ったコードがゴミになってしまわないためにも、適切に説明文を書く力は重要です。
Linuxが普及したのは、リーナス・トーバルズが文章力に長けていたから
少しコンピュータに詳しい方ならば、Linuxを知らない方はいないでしょう。
Linuxが全世界に広まったのは、ソフトウェアやコードが優れていたからだけではありません。
もちろん素晴らしいコードが数多くの派生を生み、全世界へと広まったわけですが、先ほども触れたように、コードは一番初めに見られるものではありません。
Linuxの普及の裏にあったものは、リーナス・トーバルズの文章力です。
彼が優れたハッカーであったということと同時に、e-mailやメーリングリストを通して文章で自分のアイデアを人に伝えるリーナスの能力が、世界中のボランティアをLiunxに引きつけたのだ。
このように、リーナス・トーバルズの人を惹きつける文章力がLinuxを成功に導いたと考えられます。
質の高い文章を書くための3つのポイント
質の高い文章を書くためには、具体的にどのような点に気を付ければ良いのでしょうか？
メルペイ主催のオンラインイベント「merpay Tech Talk ~伝わる技術文書の書き方~」に参加して特に印象的だった点を、文章力の観点から自分なりにまとめたうえで共有します。
アーカイブが残っているので、興味のある方はぜひ全部ご覧ください。
執筆経験豊かな3名の方が、各々違った観点から有益なお話しをされています。
それでは、質の高い文章を書くための3つのポイントについてです。
正確性とわかりやすさのバランスを考える
堅苦しい文章は読みづらい
プログラマはコンピュータを相手にしていますから、正確に書くことに関しては無意識のうちに得意になっています。
しかし文章を書く、そして伝える過程においては、正確に書くことが必ずしも正しいとは限りません。
分かりやすく言えば、Wikipedia。
Wikipediaの情報は「正しい」ことを重視して書かれていますが、それがいつもベストかと言われれば、そうとは限りません。
前提知識がない分野では、じっくり読み込まないと内容を理解できないなんて経験ありませんか？
Wikipediaの場合は、ある程度その分野に精通している人を対象に書かれてあるので、それでもOKです。
しかし、上司や顧客相手にそんなことをさせてはいけません。
- 全体像を把握してもらってから詳細に踏み込む
- 具体例を交えながら説明する
このようなわかりやすさを重視した文章構成を意識する必要があります。
相手の立場で考えてみる
いつ・どんな情報が得られたら相手は嬉しいでしょうか？
特に導入部分は重要です。
技術文書ではよくありがちですが、難しい前提条件ばかりを述べていると、本題に入る前に読者は飽きてしまいます。
本当に伝えたいことを述べる前に、読者は読むのをやめてしまうかもしれません。
まずは分かりやすい導入で読者に興味を持ってもらうことを最優先にしましょう。
第1印象がポイントです。
ソースコードも文書用にリメイク
文書にソースコードを埋め込む際、そのままコピペしてしまっていませんか？
確かに基本はコピペで問題ありません。
ですが、例えばエラー処理や例外処理。
その処理がメインの話題で無い場合、厳密に記述していても、コードの全容理解を阻害するだけの存在となってしまう恐れがあります。
「本来はここでエラー処理を行います」のようなコメントを一言挿入し、エラー処理自体は割愛してしまった方が読者に優しいですよね。
これもまた、正確性よりもわかりやすさを重視した一例です。
言葉の細かな表現に注意する
せっかく価値のある文章を書いているにもかかわらず誤字がある。
すると、それだけで文章の信頼性や説得力は失われてしまいます。
そのような、文章を書く上での細かな注意点についてまとめます。
誤字・脱字
誤字や脱字が多いと、そればかりが木になって内容が頭に入って来なくなてしまいます。
校正ツールを使用すれば、そのほとんどを無くすことができます。
merpay Tech Talkでは、具体的に以下のツールが紹介されていました。
試してみてはいかがでしょうか？
- textlint：検出ルールをプラグインとして自由に追加できるため、カスタマイズ性が高い
- RedPen：MarkdownやTextile記法の文章もそのままチェックに通すことができる
- prh：表記ゆれを検出できる（「サーバー」と「サーバ」の混在など）
- reviewdog：GitHubとセットで利用すると、文章やコードのエラーをPull Requestで指摘してくれる
※簡単な説明も書き加えてみましたが、知らなかったツールも多く、間違ったことを書いているかもしれないので、その点ご注意ください。
言葉の揺れ
コンピュータ関連のカタカナ語には、最後を伸ばしても伸ばさなくても良い用語が多くあります。
例えば「コンピュータ」なのか「コンピューター」なのかはっきりさせましょう。
どちらが間違いということではありません。
文書全体で統一されていることが大切です。
「～たり」の使い方
「～たり」は2つのことを並列させて使用します。
本を読んだり、ブログを書いて過ごす。
本を読んだり、ブログを書いたりして過ごす。
ちなみに「など」も具体例が1つでは使用できません。
Pythonなど
PythonやCなど
技術用語は正確に
略語は、初出の箇所でフルスペルで説明しましょう。
- 括弧内にフルスペルを書いて説明
CNN(Convolutional neural network) - 括弧内に略称を書き、以後その略称を使用
Deep Q Network(DQN) - 注釈を付ける
DRAW(注1)
注1…Deep Recurrent Attention Writer
このような説明がないと、いきなりCNNと出てきたら、読者はニュースサイトを想像するかもしれません。
DQNというワードを見たら、ネットスラングの方が頭に出てくるかもしれません。
DRAWは英単語として読んでしまうかもしれません。
セルフレビューを行う
自分の書いた文章を読み返し、誤字・脱字や論理の一貫性などをチェックする作業です。
セルフレビューでは、客観的に自身の書いた文章を見ることが大切です。
例えば、時間を空けて読み返してみることが挙げられます。
これは実践している方もいらっしゃるのではないでしょうか？
また今回のmerpay Tech Talkでは、「耳で聞いてみる」という方法が提案されていました。
これは音声読み上げ機能を利用して、自分の書いた文章を聞いてみるというやり方です。
耳で聞いて引っかかる箇所は、読むときにも分かりづらさを生む箇所です。
真剣に内容を聞かないとついていけない文章は、読者には伝わりません。
この「耳で聞いてみる」という方法は、文章力を高めるためにかなり有効な方法ではないかと個人的に感じました。
ぜひ実践してみてください。
実践の重要性
書かなければ上達はしない
ここまで、プログラマ視点で「文章力の重要性」と「質の高い文章を書くためのポイント」について考えてきました。
新しい気づきはありましたか？
「はい」と答えていただけたならばとても有難いです。
しかし、それで満足してしまってはいけません。
今はまだ情報が新鮮ですが、きっと明日になる頃には、その多くを忘れてしまっています。
頭で分かった気になっていても、実践しなければ身に付きませんし上達しません。
プログラム言語でもそうですよね。
参考書を眺めたり、GitHubから流用したりしているだけでは、0からコードを書けるようにはなりません。
写経を含め、やはり実際にコードを書くことが大切です。
アウトプットすると技術力も身につく
技術的な文書は、そのことについて深く知っていないと書けません。
分かった気になっている状態では書けません。
本当に理解していない状態では書けません。
学校の勉強でも、いざ友達に教えようとすると案外難しく、説明に詰まってしまったなんて経験ありませんか？
でも教えることで、自身の理解もより一層深めることができます。
それと同様です。
人に教える中で、新たな気付きが自身を高めてくれることもあるかもしれませんよ。
Qiitaやブログを始めてみよう
これまでアウトプットの習慣が無かった方。
これを機に、Qiitaやブログでアウトプットを実践してみませんか？
- いきなり言われてもうまく書けない？
- 自分のPCの中だけで練習してから？
- 人に見られるのが怖い？
これらの心配は不要です。
先ほども言ったように、書かなければ上達しません。
上手な文章を書かれている方々も、元は今のあなたと同じようなレベルからスタートしています。
アウトプットには、技術力が身につく他にも、2つのメリットがあります。
- 誰かに見られていると思うと、継続しやすい
- フィードバックをもらえる可能性がある
1人で継続することは強い意志がないと難しいですが、オープンにすることで、さぼれない環境に自分を追い込むことになります。
特にリアルの知り合いに挑戦を宣言すると効果的です。
そしてフィードバックに関しては、肯定的なものはそのままやる気や自信に繋がりますし、否定的なものも、改善のヒントを提示してくれていると捉えることができます。
いずれにせよ、自身にプラスの効果をもたらせてくれます。
ちなみにですが、ネット上には星の数ほど大量の記事があります。
心配しなくても、自分からリンクを共有していかなければ、初めのうちなんて誰にも読まれません(笑)
まとめ
プログラマはコードさえ書ければ良い。
これは大きな間違いです。
プログラマには以下のような能力も欠かせません。
- 適切なコメント…コードの価値を高めます。
- 良質な設計書や仕様書…ソフトウェアの価値を高めます。
- 情報の整ったREADME…利用者の理解を助けます。
正しく簡潔に伝える文章力を磨くことにより、これらができるワンランク上のプログラマに成長することができます。
また、文章力は次のような機会にも役立ちます。
- テックブログの執筆
- アドベントカレンダー(今まさにこの時期ですね)への参加
- LT会での発表
逆に、いきなりこれらに挑戦して文章力を磨いていくのも良いですね。
