update.ちょっと書きたくなったので書くんじゃーい!この文章を読み終わった時、読者がそれなりわかめ品質な文章を出力できるようになり、どこかに寄稿した時に全面リテイクを食らったりしないようになることを目指します。筆者は普通のエンジニアです。その辺の開発とかしてる会社に勤めています。技術系の原稿も書きます。原稿書きでご飯食べてるわけではありません(晩ご飯が豪華になることは稀にあります)。今まで有能なレビューワー(muなんとかさんとか)編集さんとか(某社の安藤さんとか)とかとかに鍛えていただきました。この場を借りてお礼を述べておきたいと思います。ありがとうございます。この文章は2013年10月時点での筆者(わかめ)のやり方です。将来的にはより良いやり方を見つけるでしょうし、これとは全く違う書き方で上手にやっている人もいると思います。これから偉そうな事述べるであろう筆者の書いた記事とかスライドとか。文章を書くのかいきなりですが、質問です。貴方は何故原稿を書こうとしているのでしょうか?考えてみましょう。自分の知識・経験に広める価値があると判断している言い換えると、何かを布教したい最新の情報について勉強したい言い換えると、ついでに原稿料貰いたいだいたいこんな所だと思います。知らない事も書いてみよう多くの人が勘違いしがちなのですが、自分が知らない事について書くというのは、実は罪ではありません。貴方は許されています。知らない事について調べて書いてもよいのです。文章を書くということは、その内容について責任を持つということと不可分です。貴方は日本語を話す人としては、一時的にであれその分野について最も詳しく知っている人になる必要があります。その分野について最も詳しく、というと死ぬほど難易度が高そうに思いますが、実のところそんなに難しいことではないのです。なるのは死ぬほど難しいと思います。限定すると、不可能ではないように思われます。そこを筆者自身の技術的到達点として狙って行きましょう。万が一、責任を持ちたくない場合は、見るからにちゃらんぽらんで、信頼がおけないような文章に仕上がるように努力しましょう。設計まず、最初にこれから作成する文章の設計を行います。設計するのは以下の要素についてです。先に書く文章の長さに応じて考える深さを変えます。この文章は深さ1で設計しました。サンプルを作成する場合、どういうサンプルを作成するか検討する実はこれがかなり難しいです説明したい要素が十分に含まれている説明しない要素かつ難しいものがなるべく含まれないようにする短いソースコードにできる説明する技術のメリット(とデメリット)が明確にわかる筆者(わかめ)の場合、この工程に意識的に取り組む時間はおおよそ10分〜2時間くらい消費されます。かける時間は短いですが、ここを真面目にやらないと後から大炎上するのは皆様も知る通りです。文章構造を考えるうえで文章構造について考える。ついて少し詳しく書いておきます。筆者が留意しているのは、読者は有限オートマトン(有限状態機械)だということです。初期状態(対象読者を考える)と受理状態(読み終わった後に読者が得られるものを考える)は既に考えてあるはずです。ここでいう章・節・項を設計することは、読者の状態を初期状態から受理状態に変化させるための途中の状態を設計することに他なりません。読者を無理なく初期状態から受理状態に遷移させるために、情報を与える順序は前後してはいけませんし、途中に歯抜けが発生してもいけません。そこを正しく行うにはどういう状態で情報を渡していけばよいのかを考え、設計を行います。示すと良いと考えています。その他の重要な点として、サンプルコードを用意する場合について。ソースコードを解説する順番に説明の順番がかなり依存するので、サンプルを用意する場合は文章構造がサンプルコードの説明をしやすい順番にできるかも考慮に入れます。それからそれから?さて、上記4要素を書ききるためには、まずは書く対象について概要を知らなければなりません。ドキュメントやサンプルコードがあれば、それに目を通して概要を掴んでおくと良いでしょう。ここまで書き終わったら、完成までにどういう事を調べなければいけないか、どういう障害がありうるか、ある程度あたりがつくようになっているでしょう。この時点で、何か憂いがある場合は解決しておきます。他の人とのネタ被り・自社の機密に抵触するか・機材や経費は許容範囲内か、などなどが考えられます。懸念事項は全てクリアしておき、もし編集さんなどの第三者がいる場合はこの時点で一旦相談しておくと良いでしょう。この辺りの手を抜いてしまうと、後々例外やエラーの処理方法を最初に設計しておかなかったシステムの如く、後から仕組みを追加してテストを追加して工数は倍々ドン!みたいな身に覚えのある辛い展開になってしまいます。ネタが被るのは悲しいことですねネタ被りについても少し言及しておきます。他の人が書いた原稿について、ネタが大なり小なり被ることはある程度仕方がない部分があります。パクリは論外ですが、ネタが被るのは仕方がないと割りきってしまいましょう。徹底的にネタ被りを避けようとするとどうなるでしょうか?英語の公式ドキュメントがあるのにそれを日本語に翻訳することは言語は違いますが内容的には完全にネタ被りなので、行わないほうがいいでしょう(実際は母国語で公式ドキュメントが読めることは多くの人にとって価値があります)。C言語についての本はたったの1冊(K&Rですかね)あれば十分で、2冊目以降はネタ被りになるので不要になります(実際は2013年にもなって未だに新しいC言語の本が出版されています)。実際には括弧内に書いた通り、ネタ被りと判定しようと思えば出来る文章でもどんどん作成されていますし、広く受け入れられています。あなたが付け加えられるオリジナルな価値・説明があればそれで良いのです。くなるので、聞いてみると良いでしょう。設計が終わったら、技術的な調査に入ります。実際のシステム開発だと、技術的な調査を行ってから設計に入ると思います。原稿の場合は本格的な調査は設計の後になります。調査フェーズで行わなければいけないのは以下のとおりです。サンプルコードの完成サンプルコードの出来によって、原稿の設計を変える必要が生じるかもしれません。完成させていきましょう。筆者(わかめ)の場合、この工程に意識的に取り組む時間はおおよそ2日〜3日(1日6〜8時間換算)くらい消費されます。実装さて、実際に原稿をもりもり書いていきましょう。設計段階で枝(章・節・項)は定義しているはずなので、そこにもさもさと葉を生やしていくだけの簡単な作業です。サンプルコードも出来ており、判明している技術的に不明な点は消化されているはずです。そのため、ここからは日本語と戦う作業になります。文章を書く時に筆者が意識的に行っている事がありますので述べていきます。日本語が一意に解釈できるか。対象読者に未知の用語を使って説明していないか説明の順番を変更する必要があれば思い切って変更する。ならないように設計時によく検討していくことも重要。筆者の中で常識だと思っている事が本当に常識かどうかを検討する。社内で常識になっているものは誤判断しやすいので留意する。常識じゃないものを常識だと判断すると、説明をすっ飛ばすというミスに派生する要求・結論を先に述べているか。オリエント急行殺人事件の犯人は☓☓☓。これから説明する内容をざっくり最初に説明するのは大事そこをサボると、読者の中に無数の解釈の枝(主旨の推測)が発生してしまい、書いてある内容がするりと入っていかなくなってしまいます。読者の計算量を減らすために積極的に枝刈りを行いましょう。言い換えを考えてみて、元の言い方と言い換えの方のどちらが意図が伝わりやすいかを検討し、必要があれば書き換える。断定口調で書けているか。不安がある場合は追加の技術的調査を行う。用語が統一され、正しく用いられているか。いう書き方が混ざっていてはいけません。それぞれ、指すものが違います。用語が正確に用いられているのかというのは、文章全体の信頼性に関わります。完全に正しくて有用な技術的文章でも、Javaの事をJavaScriptと書いて説明していたら、信頼度は地に落ち、他の部分も間違っている可能性のある、取るに足らない文章と判断されるでしょう。文章を分割できないか検討する。長い1文よりも、短い2文です。句点で切っても正しく意味が伝わる場合は積極的に切ります。文の先頭に何かをつけるのを我慢する。文の先頭に付けたくなってしまう魔力を持っています。したほうが読みやすい文に見えてしまう気がするのです。それは気のせいなのでなるべく省けるように努力します。句読点は適切に打たれているか。わかめさんめっちゃ読点多いマンです。気がついたら随時リファクタリングを行います。節の位置の交換とかも随時行いますが、なるべく最初の設計から変更しないで済むように留意します。筆者(わかめ)の場合、この工程に意識的に取り組む時間はおおよそ1日(1日6〜8時間換算)くらい消費されます。レビュワーに頼んだ後の指摘事項修正や校正などに費やす時間はここに含みません。まとめさて、いかがでしたでしょうか?みなさんもぶりばり技術文章を書いて、読んでくれた人をどんどん洗脳して自分のシンパにしましょう。僕も、こういう事を言語化して考え、なるべく体系的に把握するよう務めるようになったのも、ここ2年くらいの事です。この文章を書いて、あだむろっかとかに『2.3本書いてた奴があんな事言ってるwwwwm9(^Д^)プギャー』と煽られました。2.3本はたぶん僕が多くの人に読ませるために書いた初めての技術的文章で、あだむろっかとかますいさんにボッコボコにされた事を懐かしく思い出します。今はあの時よりはマトモになってると思うんですけどね。簡潔に言うと、最初はクソみたいな文章を出力してしまうものだし、使い古されている言葉ではありますが継続は力なり、ということです。恐れず、クソを生産して周囲の識者にボコボコにしてもらえたら最初の洗礼を受けられた、と捉え一安心すると良いと思います。この文章を書くにあたり、編集履歴に作業風景がなるべく残るようにしてみました。興味があればご覧ください。これだけの文章を書くのに約3時間かかっているようですね。短いのか長いのかもわかりませんが。requestStockLike1259@vvakameFollowMercariフリマアプリ「メルカリ」を、グローバルで開発しています。upLoginユーザーは見つかりませんでした。