これはフィードフォースエンジニア Advent Calendar 2015の22日目の記事です。
21日目は "ウォシュレットではなく、トイレットペーパー派" 茂木くんのruby の構文解析器 astrolabe を使ってみたでした。
そういえば、昔文章を書く勉強をしてたんでした。
もう 15 年とか昔の話だけど。
で、最近思ったのが。
「自分が文章を書く時と、開発してる時って、実は同じようなこと考えて作業を進めてる」
ってこと。
というわけで、文章の書き方を開発行程に雑に例えて、文章をどうやって書き上げるかという話をしようと思った。
とりあえず「ユーザストーリー」って言ってみただけ。
開発も最初はここから。
文章も同じ。
これから自分が何を書くかを決めるってこと。
つまり
「SQL可愛い！」
みたいなこと。
開発だと、ストーリーそのままだと実装できないから細かな作業に分解するよね。
文章も同じ。
今回は「SQL 可愛い！」をどうやって伝えるか。
「SQL 可愛い！」っていうのは、自分にとって「SQL 大好き！」みたいなものなので、普通に考えたら「なんで好きなのか」って話をしたら良いのかもしれない。
ただ「なんで好きか」ってそんなにすぱっと説明できるものじゃないよね。
ありがちシーンで恋人が「わたしのどこが好きなの？」って聞くやつあるけど、理屈じゃない部分は説明できないよね。
そもそもストーリーが間違ってるのだろうか？
いや、今自分は「SQL 可愛い！」って思ってることに嘘はないんだから、間違ってない。
そんなことを考えていた時に、昔(SQL 初心者時代)に勉強してた時のメモが出てきた。
JOIN するテーブルをサブクエリにしたら速くなった！ とか戸惑ってて初々しいなー。
とか思って見返してたんだけど、要するに昔は SQL (RDB) のことがよくわかってなかったということ。
今の自分はその頃より、わかっているだろうか？
それって、SQL と自分の距離感と言っても良いのかなーみたいなことを思いついて「SQL と距離を縮める」話にしよう、と思った。
- 最初はすごく距離が遠い気がしてた
- SQL のことを勉強して、いろいろわかるようになったら、距離が近付いた気がする
- 距離が近付いたら、より好きになった
つまり、
好き 👉 だから仲良くなりたい 👉 勉強して近付いた 👉 距離が縮まる 👉 もっと好きになる 👉 可愛い！
ということ！
タスクとして分解したものを言語化するなら、こんな感じ
- 好きだから仲良くなりたい
- 仲良くなるためには相手を知ることが大事だよね
- SQL と仲良くなるのに困惑するポイントも、知れば「可愛い」になる
ORDER BYが遅いのは全件処理をしようとするから 👉 健気可愛い- SQL の結果が返るまでの仕事量を考えてみる 👉 SQL の気持ちがわかるようになる
- 構造とかデータの状況とかで何が有効かって変わるよね 👉 都度 SQL と向き合う
で、どうせなら比喩過多にして「SQL 可愛い！」って言うだけの記事を書こうと思った。
モデルっていうかオブジェクト。
「SQL(可愛い)」
「自分(SQL可愛いって思ってる)」
「RDB」
みたいな。
その関係は？
「自分がRDB操作のためにSQLを使う」
「SQLはRDB操作して結果を自分に返してくれる(可愛い)」
(何か図を入れるか)
これ、実際に働いているのは SQL じゃなくて RDB だよなー、でも自分は RDB じゃなくて SQL の話したいんだよなー、としばし悩んだ。
その辺りを明確にしようとすると SQL の話じゃなくて RDB の話になってしまいそうだったので、そこは限りなくぼかそうと思った。
つまり RDB のことは意図的に無視して、文章内では「自分」と「SQL」二人だけの世界にしてしまおう、ということ。
実は、比喩過多にしたのは、その辺りを誤摩化したかったからもある。
技術的なテキストとしてその辺りをぼかすのは良心が痛むが、ポエムなら割り切れる。
自分は「SQL がいかに可愛いか」のポエムを書くんだ、と改めて自分の書くものの方向性をここで再認識した。
なので、文章の最初の方に「これは技術的な正確さを重視してない文章ですよ」というエクスキューズを入れよう、と思った。
まずはテストから。
文章のテストって言うと謎っぽいけど、仕様って言っても良い。
あるいは、骨組みって言った方が伝わるかも。
タスクとして分解したものを骨組みにする。
自分はよく「タスク(文章的には段落)毎に」「そこで何を伝えるか」を箇条書きにする。
その結果、「更にタスクが増える」こともあるし、逆に「二つにわけて書いてたけど実は同じタスクだった」みたいなこともある。
例をあげると、こんな感じ。
https://gist.github.com/kano-e/8d75be08037809fd280d/4d9800a5237e17df49027f9a96f092d2e45a7635
この時点では、「全部実装できるか(書ききれるか・書く必要があるか)」は考えない。
とにかく「こういうことも伝えたい」ってことがあったら、とにかく書き出して、どこかの段落に投入する。
適切な段落がなければ、新しい段落を検討する。
ちなみに「こういうことは書かない」って決めたことがあれば、宣言的に箇条書きに追加しておくと良い。
「こういう時は動かない」というテストのように。
後は、テスト(骨組み)の通りに文章を書いてゆくだけ。
この時に「箇条書きで書いたものを修飾して文章にする」ということを やっては駄目 だと思ってる。
気分の問題かもしれないけど。
箇条書きを横目で見ながら、新しい文章を書く方が書きやすいし、新鮮な気持ちで楽しく書ける。気がする。
新鮮な気持ちって大事で。
たとえ、自分が書いた箇条書きの文章でも、それを切り貼りして作った文章は「コピペ文章」になってしまう感じある。
うーん、例えば。
コード書いてる途中で調べものして、どこかで参考であげられたコードをコピペして、自分のコードに合わせてちょこちょこっと修正して差し込むとか、よくないよね？
それを理解できてない場合には。
で、コードを理解できてる時には「コピペ」にはならないよね？
結果的に同じコードになったり、実際にはコピペしたとしても。
自分の箇条書きの文章もそれと同じ。
いくら自分が書いていても「実はよくわかってない」ってことがあるから。
「それを理解」できてるならコピペでも良いんだけど、自分の経験から考えると、理解できている時にはあまり「コピペ」したくならない。
で、だ。
この時点では、まだ細かな言い回しととか、語尾がどうとかは意識しない。
とにかく、全体を仕上げるのが大事。
さっきの仕様を実装したものが、これ。
https://gist.github.com/kano-e/8d75be08037809fd280d/0b82870ad40fe21f9e7099a6630d98e3e60a7a54
というのは、ちょっとだけ嘘で。
これコミットしたタイミングで実は少しリファクタリング(後述)してしまってた気がする。
(確か Evernote かどこかでそこまでやっちゃった覚えある)
全体が書き上がったら、リファクタリング。
リファクタリングにも段階があって。
- 全体の流れ(骨組み)に問題がないか？ を見る
- 最初に書きたかったこととずれてないか？
- 不必要なものがあるか？
- 意味のない繰り返し
- 冗長な説明
- 必要なのに足りてないものがないか？
- 説明不足
- 曖昧になっている
- 強調しないといけないところで強調できてない
- 流れはおかしくないか？
- 話があちこち飛んでいる
- 話の順序がおかしい (先に説明しないと伝わらない)
- 矛盾してる言い回し
- 文章の整合性
- 文体の統一
- 語句のレイヤを揃える
- スラングや流行語的なものはどの程度使うか、とか、技術的な言葉はどこまでアリにするか、とかそういうこと
- 主語 (自分の立ち位置や姿) にブレがないようにする
- 細かなところ
- 表記揺れ
- 漢字/かなのチェック
- 語尾のリズムとか
- 改行や句読点、スペースを整えたり
と、考えると最低 3回かなあ。
1 について考えるべき時に 3 について修正はじめちゃうとうまくいかないし、その修正が結局無駄になること多いと思う。
あと、自分の文章を削ることと、書き直すことを恐れない方が良い。
最初の「ユーザストーリーから外れないのであれば」「仕様の方を書き直して」「実装しなおせば」良い。
残しておいてもバグにしかならないコードは削除したら良い。
コードレビューみたいに誰かに見てもらうのは効果的なんだけど、コードレビューの依頼と同じで、レビューする前に自分で見返して「見てもらう」状態まで持って行かないと効果は薄いよとは思ってる。
で、自分で自分の文章を音読するのは、結構効果的。
これは自分で自分のレビューをしてるようなもの。
何度もリファクタリングして「ここまで」と思ったら公開したら良い。
諸事情で、納得いかなくても公開しないといけないこともあると思うけど、まあ、そういうこともありますよね。
そんなこんなで出来上がったのがSQL と仲良くなる話なわけです。
ちなみに、この文章自体は突貫工事でリファクタリング足りてない！
(公開後に少しずつ修正するけどね)
さいごの方、疲れてきて「開発行程に例える」っていうを諦めかけてしまった……。
まあ、実際の開発と同じで「それについて調査する」とか「実装してみたら思ってたようにはいかなかった」とか、色々とあるよね。
文章について細かいことを言うなら「使い慣れない言葉を使わない」とか「言葉の意味をきちんと調べる」みたいなこともあるし。
そもそも「良い文章」についての基準が自分の中にないと、リファクタリングしても効果が薄いってこともある。
それがわかるようになるためには「良い文章」を読むと良いと思ってる。
ストーリーテリングとか構成とか面白がらせるとかのテクニックが上手な文章を「良い文章」だと誤解しがちだけど、そういう「上手さ」と「文章の善し悪し」は別だと思うし、そこを区別できるようになりたい。
コーディング規約みたいに、文章を書く時のルールがあった方が良いよね、みたいなこともある。
この辺り、参考 URL をいくつかあげようと思ったけど、諦めたのでそれぞれ頑張って探してください。
「Web で読まれる文章の書き方 Tips」ではなく、一度は「文章の書き方」を知った方が良いと思ってる。
だって、本家のドキュメント見ずに、Tips だけでプログラミングしないよね？
とかとか。
そんなようなことを考えてたりするので、プログラミングできる人って大抵は文章も書けるんじゃないかなーとか思ってる。
うん、頑張ろう。頑張る。頑張って書けるようになりたい。なる。
23日目は糖質制限でスリムになったtmd45さんの受付システムつくってみた（仮）です。
受付システム、はやく使ってみたい！