技術文書を書く際の、心技体

技術文書を書く際の、心技体

1. 1. 技 術 文 書 を 書 く 際 の 、 心 技 体 @icoxfog417
2. 2. 1 技術文書の定義 技術文書の心技体 心：記事を書くときの心構え 体：技術文書の構成要素とその目的 技：各要素の書き方 演習問題
3. 3. 2 今から解説を行う技術文書とは、何かしらの技術的な知識を、 「他者 へ伝達することを目的として」書かれた文書とします。 そうした意味では、本稿で扱う技術文書の書き出しは「他者に伝えた い」というモチベーションから始まります。 本文書は、その思いを最大限活かすために書かれた「技術文書」です。
4. 4. 3 技術文書における「心技体」とは なんなのか、説明します。 序 体 心 技 技術文書を書く際に、意識してお くべき点について解説します。 技術文書の基本的な構成について 解説します。 技術文書を書く「技術」について、 具体例を交えながら解説します。
5. 5. 4 ここからは、技術文書を書くための手法について、心・技・体に分けて 解説をしていこうと思います(※構成の都合上、解説の順番は心・体・ 技になります)。 具体的には、以下の点について解説をしていきます。 心：技術文書を書く上で、意識しておくべきこと 体：技術文書の構成 技：読んでもらうためのテクニック
6. 6. 心
7. 7. 6 技術文書を読むという行為を通じて、読み手は新しい知識を獲得します。 それは一つの「体験」と捉えることができ、音楽を聴く、映画を見ると いった行為と何ら変わりません。新しい知識の獲得は、人間にとって、 技術者にとってはなおさら、本来的に魅力的な体験だからです。 この過程をどうデザインするのか、という観点を持つと文章の書き方は かなり変わってくると思います。大げさに言えば、作曲家や映画監督の 視点を入れてみるということです。 読み手の「知識獲得の体験」をデザインする
8. 8. 体
9. 9. 8 技術文書の構成は、目的別に大きく以下の3つに分けることができます。  タイトル：文章を開いてもらう(クリックしてもらう)  前文 ：文章を読んでもらう  本文 ：技術を理解してもらう 読み手の目線から言えば、タイトルで文章を開くか判断し、前文で読み 続けるか決め、そこから初めて本文にふれるということです。
10. 10. 9 勝負の「第一印象」 特にタイトル・前文は以下のよう に「第一印象」を決める重要な要 素になります。  一覧に表示されるテキスト  記事を開いた際表示される範囲  SNSなどで共有される際に表示 されるサムネイル・テキスト (20~50文字)
11. 11. 技
12. 12. 11 文書を読んでもらうには、人のモチベーションを喚起する必要がありま す。この「人のモチベーション」には以下7種類の要因があります。こ れらを理解することは、魅力的な体験の演出に役立ちます。 帰属意識 習慣 物語の力 アメとムチ 本能 熟達願望 心の錯覚 次のスライドで簡単に紹介しますが、詳 細は長くなるので、興味がある方は↓を 読んでみてください。 説得とヤル気の科学 ―最新心理学研究が解き明かす 「その気にさせる」メカニズム
13. 13. 12 帰属意識 習慣 物語の力 アメとムチ 本能 熟達願望 心の錯覚 自分と同じ境遇と感じる人に言われると行動しやすい。 いつも行っていることに関連することは行いやすい。 自分自身の性格や希望像に沿うことは行いやすい。 自分が既に知っていることや明確なことだと行いやすい。 報酬がもらえるなら行動しやすい。 危機感や希少性があることについては行動しやすい。 挑戦し甲斐があり、成長が実感できるものは行動しやすい。
14. 14. 13 これらのモチベーションを喚起する要素を踏まえた上で、各パートを書 く際にこれらをどのように活かしていくのかについて、見ていきます。  タイトル  前文  本文
15. 15. 14 タイトルは文章を開いてもらうための最も重要なパーツになります。モ チベーションを喚起する要素を駆使し、「読みたくなるような」タイト ルを付けます。  帰属意識：数式で挫折した人たちに贈る、初歩からの機械学習  物語の力：フルスタックエンジニアになるための、基礎知識総ざらい  本能：2017年をサヴァイブするためのJavaScript開発環境  熟達願望：関数型プログラミングの鬼門、モナドにチャレンジ  心の錯覚：TensorFlowを算数で理解する
16. 16. 15 タイトルは重要であるぶん、過激な表現になりがちです。しかし、技術 文書は他者にクリックさせることが目的ではなく、技術を伝えることが 目的です。 基本的に、きちんとした内容であれば成果はしっかりついてきます。読 み手に、またあなた自身が伝える技術に誠実にタイトルを付けてくださ い。そこに、少しの遊び心をいれるというのが良い配分と思います。 誠実さと遊び心
17. 17. 前文は記事を「読み続けるか」判断するための重要なパートになります。 どれだけ良いタイトルを付けても、前文が悪ければ文書は閉じられてし まいます。 前文で特に重要となるモチベーションの要素は、 以下の3つです。 まず「現状の状態」を共有し(帰属意識)、そこから抜け出すための「獲得 し甲斐のある知識」を提示する(熟達願望)。そして「それを獲得するス トーリー」を明示する(物語の力)、というのが基本的な流れになります。 熟達願望 物語の力 16 帰属意識
18. 18. 17 TensorFlow。挑戦したいけれども、そもそも機械学習も知らない自分に は難しい・・・と感じる方も多いのではないかと思います。 そこで、本記事では機械学習の仕組み、そしてTensorFlowでの実装方法 を、算数程度の簡単な演算をベースに解説していきたいと思います。 熟達願望 物語の力帰属意識
19. 19. 18 TensorFlow。挑戦したいけれども、そもそも機械学習も知らない自分に は難しい・・・と感じる方も多いのではないかと思います。 そこで、本記事では機械学習の仕組み、そしてTensorFlowでの実装方法 を、算数程度の簡単な演算をベースに解説していきたいと思います。 熟達願望 物語の力帰属意識
20. 20. 19 TensorFlow。挑戦したいけれども、そもそも機械学習も知らない自分に は難しい・・・と感じる方も多いのではないかと思います。 そこで、本記事では機械学習の仕組み、そしてTensorFlowでの実装方法 を、算数程度の簡単な演算をベースに解説していきたいと思います。 熟達願望 物語の力帰属意識
21. 21. 20 本文に記載される技術情報は、読み手に取って未知の事柄になります。 この「未知の技術の習得」を楽しんでもらうのが、「知識獲得の体験」 をデザインするということになります。 そのために重要なのが、まず地図(全体像)を明示するということです。 見知らぬ土地に行く際はまず地図を買うように、明確な道筋が見えると 不快感がなくなり期待感が醸成されます。 これを行った上で、読み進めてもらうために構成を工夫します。 読み手の頭の中に地図を作る
22. 22. 21 読み進めてもらう、つまり読むモチベーションを喚起するのに使える要 素は以下の3点です。 読み手の体験を想像する 熟達願望 アメとムチ心の錯覚 読み手が既に理解しているであろうことに例えるのは、理解の促進に役 立ちます(心の錯覚)。そして 「読む→理解！」という成功体験が都度得 られる単位に解説を分けることで、読む意欲を保つことができます(熟 達願望/アメとムチ)。
23. 23. 22 Reactで作成するアプリケーションの構造は、古き良き(?)ピラミッド型の 組織にとてもよく似ています。React社会において組織の構成員は Componentと呼ばれ、データを受け取るとそれを処理します。このデータ は必ず上位の組織から流れてくることになっており、どれだけ横にパス したほうが効率が良くても、必ず上を通してデータを伝達します。効率 のよさよりも、規律を重んじるのがReact Wayというわけです。 心の錯覚 全体像の提示
24. 24. 23 本記事は、理解・実践・応用という3ステップでこのReact社会で生きる 術を学んでいきます。 ・理解：React社会の掟を、実際のコードも交え理解します ・実践：簡単なToDoアプリを作成することで、その扱い方を理解します ・応用：現場で導入する際に必要となる追加知識について、理解します では、はじめていきましょう！ アメとムチ熟達願望
25. 25. 実践
26. 26. 25 以下に、書きやすそうなテーマをいくつか用意してみました。実践編と して、これらをテーマにタイトルと前文、本文の構成までを考えて、実 際に書き出してみてください。  機械学習  フロントエンド界隈の技術  職場で実践しているノウハウ(テストやCIなど)  好きなエディタやツール、言語の普及  最近の失敗や障害から学んだ知見
27. 27. 26 Have a Good Writing!