SlideShare a Scribd company logo

技術文書を書く際の、心技体＜改訂版＞

•
•
Takahiro Kubo
Takahiro Kubo

本資料は、技術文書を書くためのテクニックについて書かれた文書です。 解説は、心・技・体の3つの点から行います。 　心：技術文書を書くときの心構え 　技：技術文章の書き方 　体：技術文章のネタを育てる方法 書く前に「心」を整え、「技」でもって育てたネタ「体」を読み手に届ける、という流れです。解説もこの順に沿って行っていきます。

1 of 42
Downloaded 35 times
技 術 文 書 を 書 く 際 の 、 心 技 体 @icoxfog417 改訂版
1 本資料は、技術文書を書くためのテクニックについて書かれた文書です。 解説は、心・技・体の3つの点から行います。 心：技術文書を書くときの心構え 技：技術文章の書き方 体：技術文章のネタを育てる方法 書く前に「心」を整え、「技」でもって育てたネタ「体」を読み手に届 ける、という流れです。解説もこの順に沿って行っていきます。
2 解説を始める前に、「技術文書」 の定義をします。 序 技 心 体 技術文書を書く際に、意識してお くべき点について解説します。 技術文書を書く「技術」について、 具体例を交えながら解説します。 日々の気づきというネタを、技術 文章というコンテンツまで育てる 方法を解説します。
序
4 今から解説を行う技術文書とは、何かしらの技術的な知識を 「他者へ 伝達すること」を目的として書かれた文書とします。 内容が技術的なものであるため、感動を伝えるなどエモーショナルなも のは対象としません。また、他者に伝えるものであるため、個人的なメ モや日記のようなものも対象としません。 こうした文書を書くことは、知識の共有に役立つだけでなく、自分の理 解をより深いものにするという面でも役立ちます。
心
技術の内容を、素早く、正確に伝えるべし 読み手のモチベーションを喚起すべし 読まれない文書は自分のせいと心得るべし 6
7 これが技術文章が目指す一つの到達点です。読み手は短い時間でその技 術について知りたいと思っているわけですから、その思いをくみ取る必 要があります。 「わかりやすさ」というのは、そのための手段です。わかりやすければ 短い時間で理解ができます。ただ、正確性を損なってはいけません。 「面白さ」も手段のうちの一つです。楽しいほど体感時間が短くなるた めです。ただ、面白さ重視で冗長に、また誤解を招く内容になってはい けません。 技術の内容を、素早く、正確に伝えるべし
8 多くの場合、技術文書は「読むのが必須」なわけではありません。その ため、より多くの人に読んでほしい場合は工夫が必要です。 技術文章を読む＝勉強をするのは誰でも嫌なのでは？と思うかもしれま せんが、「新しい知識の獲得」という体験は人間にとって、技術者に とってはなおさら、本来的に魅力的な体験です。 自分の文章を通じどんな体験をしてもらうか？という観点を持つと、文 章の書き方はかなり変わってくると思います。大げさに言えば、作曲家 や映画監督の視点に立つということです。 読み手のモチベーションを喚起すべし
9 読まれない文章というのは、前述の2点について何かしら失敗をしてい る文章、ということです。つまり、内容が素早く理解できないか、読む 気のおこらない文章ということです。これを読み手の理解度や意識の問 題にしてはいけません。 書き手は、最も「甘い」読み手と言えます。なぜなら、記事に書かれて いる内容をすべて把握しているからです。自分の評価と実際の評価を近 づけていくには、「技」が必要になってきます。 読まれない文書は自分のせいと心得るべし
技
構成要素の役割を理解する モチベーションの秘孔をつく 読み飛ばせる構成で書く 11
12 技術文書は、以下3つの構成要素に分けることができ、それぞれに役割 があります。  タイトル：文章を開いてもらう(クリックしてもらう)  前文 ：文章を読んでもらう  本文 ：技術を理解してもらう 読み手の目線から言えば、タイトルで文章を開くか判断し、前文で読み 続けるか決め、そこから初めて本文にふれるということです。
13 勝負の「第一印象」 特にタイトル・前文は「第一印 象」を決める重要な要素になりま す。  一覧に表示されるテキスト  記事を開いた際表示される範囲  SNSなどで共有される際に表示 されるサムネイル・テキスト (20~50文字)
14 文書を読んでもらうには、人のモチベーションを喚起する必要がありま す。この「人のモチベーション」には以下7種類の要因があります。こ れらを理解することは、魅力的な体験の演出に役立ちます。 帰属意識 習慣 物語の力 アメとムチ 本能 熟達願望 心の錯覚 次のスライドで簡単に紹介しますが、詳 細は長くなるので、興味がある方は↓を 読んでみてください。 説得とヤル気の科学 ―最新心理学研究が解き明かす 「その気にさせる」メカニズム
15 帰属意識 習慣 物語の力 アメとムチ 本能 熟達願望 心の錯覚 自分と同じ境遇と感じる人に言われると行動しやすい。 いつも行っていることに関連することは行いやすい。 自分自身の性格や希望像に沿うことは行いやすい。 自分が既に知っていることや明確なことだと行いやすい。 報酬がもらえるなら行動しやすい。 危機感や希少性があることについては行動しやすい。 挑戦し甲斐があり、成長が実感できるものは行動しやすい。
16 これらのモチベーションを喚起する要素を踏まえた上で、各パートを書 く際にこれらをどのように活かしていくのかについて、見ていきます。  タイトル  前文  本文
17 タイトルは文章を開いてもらうための最も重要なパーツになります。モ チベーションを喚起する要素を駆使し、「読みたくなるような」タイト ルを付けます。  帰属意識：数式で挫折した人たちに贈る、初歩からの機械学習  物語の力：フルスタックエンジニアになるための、基礎知識総ざらい  本能：2017年をサヴァイブするためのJavaScript開発環境  熟達願望：関数型プログラミングの鬼門、モナドにチャレンジ  心の錯覚：TensorFlowを算数で理解する
18 タイトルは重要であるぶん、過激な表現になりがちです。しかし、技術 文書は他者にクリックさせることが目的ではなく、技術を伝えることが 目的です。 基本的に、きちんとした内容であれば成果はしっかりついてきます。読 み手に、またあなた自身が伝える技術に誠実にタイトルを付けてくださ い。そこに、少しの遊び心をいれるというのが良い配分と思います。 誠実さと遊び心
前文は記事を「読み続けるか」判断するための重要なパートになります。 どれだけ良いタイトルを付けても、前文が悪ければ文書は閉じられてし まいます。 前文で特に重要となるモチベーションの要素は、 以下の4つです。 まず「現状の状態」を共有し(帰属意識)、そこから抜け出すための「獲得 し甲斐のある知識」を提示する(熟達願望)。そして「それを獲得するス トーリー」を明示する(物語の力)、というのが基本的な流れになります。 熟達願望 物語の力 19 帰属意識 心の錯覚
20 TensorFlowを使いこなしてみたい。けれども、そもそも機械学習も知ら ない自分には難しい・・・と感じる方も多いのではないかと思います。 そこで、本記事では機械学習の初歩的なところから、TensorFlowで実際 に実装するまでのプロセスを、算数程度の簡単な演算をベースに解説し ていきたいと思います。 熟達願望 物語の力帰属意識 心の錯覚
21 TensorFlowを使いこなしてみたい。けれども、そもそも機械学習も知ら ない自分には難しい・・・と感じる方も多いのではないかと思います。 そこで、本記事では機械学習の初歩的なところから、TensorFlowで実際 に実装するまでのプロセスを、算数程度の簡単な演算をベースに解説し ていきたいと思います。 熟達願望 物語の力帰属意識 心の錯覚
22 TensorFlowを使いこなしてみたい。けれども、そもそも機械学習も知ら ない自分には難しい・・・と感じる方も多いのではないかと思います。 そこで、本記事では機械学習の初歩的なところから、TensorFlowで実際 に実装するまでのプロセスを、算数程度の簡単な演算をベースに解説し ていきたいと思います。 熟達願望 物語の力帰属意識 心の錯覚
23 TensorFlowを使いこなしてみたい。けれども、そもそも機械学習も知ら ない自分には難しい・・・と感じる方も多いのではないかと思います。 そこで、本記事では機械学習の初歩的なところから、TensorFlowで実際 に実装するまでのプロセスを、算数程度の簡単な演算をベースに解説し ていきたいと思います。 熟達願望 物語の力帰属意識 心の錯覚
24 本文に記載される技術情報は、読み手に取って未知の事柄になります。 この「未知の技術の習得」を楽しんでもらうのが、「知識獲得の体験」 をデザインするということになります。 そのために重要なのが、まず地図(全体像)を明示するということです。 見知らぬ土地に行く際はまず地図を買うように、明確な道筋が見えると 不快感がなくなり期待感が醸成されます。 これを行った上で、読み進めてもらうために構成を工夫します。 読み手の頭の中に地図を作る
25 読み進めてもらう、つまり読むモチベーションを喚起するのに使える要 素は以下の3点です。 読み手の体験を想像する 熟達願望 アメとムチ心の錯覚 読み手が既に理解しているであろうことに例えるのは、理解の促進に役 立ちます(心の錯覚)。そして 「読む→理解！」という成功体験が都度得 られる単位に解説を分けることで、読む意欲を保つことができます(熟 達願望/アメとムチ)。
26 Reactで作成するアプリケーションの構造は、古き良き(?)ピラミッド型の 組織にとてもよく似ています。React社会において組織の構成員は Componentと呼ばれ、データを受け取るとそれを処理します。このデータ は必ず上位の組織から流れてくることになっており、どれだけ横にパス したほうが効率が良くても、必ず上を通してデータを伝達します。効率 のよさよりも、規律を重んじるのがReact Wayというわけです。 心の錯覚 全体像の提示
27 本記事は、理解・実践・応用という3ステップでこのReact社会で生きる 術を学んでいきます。 ・理解：React社会の掟を、実際のコードも交え理解します ・実践：簡単なToDoアプリを作成することで、その扱い方を理解します ・応用：現場で導入する際に必要となる追加知識について、理解します では、はじめていきましょう！ アメとムチ熟達願望
28 「素早く」伝えるには、そもそも読まないのが最速です。つまり、いか に「読み飛ばしてもらえるか」が重要ということです。 読み飛ばしに重要なのが「パラグラフ」です。パラグラフは1トピック について、先頭に要約、その後に補足情報を書いたブロックです。読み 手は、要約を見て十分であれば、次のパラグラフに移ることができます。 [要約＋補足情報]のブロック=パラグラフで書く
29 Dockerは、アプリケーションの動作環境を「コンテナ」にまとめる技術 です。コンテナはDockerfileという定義書に従い作成され、このファイル さえあればどこでもコンテナを作成することが可能です。 Dockerコンテナにより、アプリケーションのポータビリティが向上しま す。具体的には、開発環境で動いたが本番環境で動かないといった事態 を防げる他、様々な環境へのデプロイも容易になります。 Dockerは既存の仮想化技術と異なり仮想サーバーを必要としません。複 数のコンテナは同じOSを共有する複数のユーザーと同等で、ユーザーの 仮想化とも言えます。このためビルドや立ち上げが高速です。
30 Dockerは、アプリケーションの動作環境を「コンテナ」にまとめる技術 です。コンテナはDockerfileという定義書に従い作成され、このファイル さえあればどこでもコンテナを作成することが可能です。 Dockerコンテナにより、アプリケーションのポータビリティが向上しま す。具体的には、開発環境で動いたが本番環境で動かないといった事態 を防げる他、様々な環境へのデプロイも容易になります。 Dockerは既存の仮想化技術と異なり仮想サーバーを必要としません。複 数のコンテナは同じOSを共有する複数のユーザーと同等で、ユーザーの 仮想化とも言えます。このためビルドや立ち上げが高速です。 Topic: What is Docker? Topic: Merit of Docker Topic: Difference btw VM
31 パラグラフを使って書いていくことで、読み飛ばしが可能になります。 ※本当は4～8文くらいのまとまりです(先ほどの例は、スライドにおさめ るため端折っています)。 パラグラフには、1トピックのみを収めるようにします。そうしないと、 読み飛ばした場合に要約に含まれていないトピックの情報が落ちてしま うためです。 より詳しく知りたい方はこちらをお勧め 論理が伝わる 世界標準の「書く技術」 (ブルーバックス)
体
日々学んだことを記録すべし 学んだことを垂直に育てる 学んだことを水平に育てる 33
34 机の前に座って、さあ書こうといっても難しいのは当たり前です。 日々の仕事の中で、学んだことはいくつもあるはずです。それを忘れず に書き留めておきます。 ただ、それらはそのままでは記事にするほどのボリュームがないことが ほとんどです。そのため、「育てる」作業が必要になります。 この育て方として、垂直型と水平型の2種類があります。
35 垂直に育てるのは、見つけたネタをより掘り進めていく育て方です。  最適化: SELECTのJOINについて学んだ  「より」パフォーマンスの良い書き方は？  活用: Dockerについて学んだ  Herokuで使うには？ 実案件で使うには？  歴史: JavaScriptのPromiseについて学んだ  Promiseが発明された歴史的な背景は？
36 水平に育てる、とは見つけたネタと比較/並列関係にある情報を集めてい くという育て方です。  比較: Terraformについて学んだ  AnsibleやChefとの違いは？  列挙: SQLについて学んだ  各データベースでの方言の違いは？  分類: AWSについて学んだ  各PaaSサービスは、その性質によりどう分類できるか？
実践
38 以下に、書きやすそうなテーマをいくつか用意してみました。実践編と して、これらをテーマにタイトルと前文、本文の構成までを考えて、実 際に書き出してみてください。  機械学習  フロントエンド界隈の技術  職場で実践しているノウハウ(テストやCIなど)  好きなエディタやツール、言語の普及  最近の失敗や障害から学んだ知見
39 今まで自分が書いた記事を、パラグラフ単位の構成になるよう書き直し てみてください。 パラグラフの掟  1トピックについて書く  最初に要約、次に補足説明  全体で4～8文が目安
40 以下に、日ごろ学んだこととしてありえそうなものを用意してみました。 垂直型、水平型に育ててみて、どんな記事が書けそうか考えてみてくだ さい。  GitでPull Requestを送る手順について学んだ  Bootstrapに飽きたので他のCSSフレームワークについて調べた  TensorFlowでMNISTに入門してみた  重たいSQLのパフォーマンスチューニングを行った  普段使わない、新しい言語を学んでみた
41 Have a Good Writing!

More Related Content

技術文書を書く際の、心技体＜改訂版＞