技術文書を書く際の、心技体＜改訂版＞
32 likes12,500 views
本資料は、技術文書を書くためのテクニックについて書かれた文書です。 解説は、心・技・体の3つの点から行います。 心：技術文書を書くときの心構え 技：技術文章の書き方 体：技術文章のネタを育てる方法 書く前に「心」を整え、「技」でもって育てたネタ「体」を読み手に届ける、という流れです。解説もこの順に沿って行っていきます。
![28
「素早く」伝えるには、そもそも読まないのが最速です。つまり、いか
に「読み飛ばしてもらえるか」が重要ということです。
読み飛ばしに重要なのが「パラグラフ」です。パラグラフは1トピック
について、先頭に要約、その後に補足情報を書いたブロックです。読み
手は、要約を見て十分であれば、次のパラグラフに移ることができます。
[要約＋補足情報]のブロック=パラグラフで書く](https://image.slidesharecdn.com/howtowritetecharticle-171208110223/85/-29-320.jpg)
技術文書を書く際の、心技体＜改訂版＞
- 1. 技 術 文 書 を 書 く 際 の 、 心 技 体 @icoxfog417 改訂版
- 4. 序
- 6. 心
- 11. 技
- 13. 12 技術文書は、以下3つの構成要素に分けることができ、それぞれに役割 があります。 タイトル：文章を開いてもらう(クリックしてもらう) 前文 ：文章を読んでもらう 本文 ：技術を理解してもらう 読み手の目線から言えば、タイトルで文章を開くか判断し、前文で読み 続けるか決め、そこから初めて本文にふれるということです。
- 14. 13 勝負の「第一印象」 特にタイトル・前文は「第一印 象」を決める重要な要素になりま す。 一覧に表示されるテキスト 記事を開いた際表示される範囲 SNSなどで共有される際に表示 されるサムネイル・テキスト (20~50文字)
- 18. 17 タイトルは文章を開いてもらうための最も重要なパーツになります。モ チベーションを喚起する要素を駆使し、「読みたくなるような」タイト ルを付けます。 帰属意識：数式で挫折した人たちに贈る、初歩からの機械学習 物語の力：フルスタックエンジニアになるための、基礎知識総ざらい 本能：2017年をサヴァイブするためのJavaScript開発環境 熟達願望：関数型プログラミングの鬼門、モナドにチャレンジ 心の錯覚：TensorFlowを算数で理解する
- 31. 30 Dockerは、アプリケーションの動作環境を「コンテナ」にまとめる技術 です。コンテナはDockerfileという定義書に従い作成され、このファイル さえあればどこでもコンテナを作成することが可能です。 Dockerコンテナにより、アプリケーションのポータビリティが向上しま す。具体的には、開発環境で動いたが本番環境で動かないといった事態 を防げる他、様々な環境へのデプロイも容易になります。 Dockerは既存の仮想化技術と異なり仮想サーバーを必要としません。複 数のコンテナは同じOSを共有する複数のユーザーと同等で、ユーザーの 仮想化とも言えます。このためビルドや立ち上げが高速です。 Topic: What is Docker? Topic: Merit of Docker Topic: Difference btw VM
- 33. 体
- 36. 35 垂直に育てるのは、見つけたネタをより掘り進めていく育て方です。 最適化: SELECTのJOINについて学んだ 「より」パフォーマンスの良い書き方は？ 活用: Dockerについて学んだ Herokuで使うには？ 実案件で使うには？ 歴史: JavaScriptのPromiseについて学んだ Promiseが発明された歴史的な背景は？
- 37. 36 水平に育てる、とは見つけたネタと比較/並列関係にある情報を集めてい くという育て方です。 比較: Terraformについて学んだ AnsibleやChefとの違いは？ 列挙: SQLについて学んだ 各データベースでの方言の違いは？ 分類: AWSについて学んだ 各PaaSサービスは、その性質によりどう分類できるか？
- 38. 実践
- 39. 38 以下に、書きやすそうなテーマをいくつか用意してみました。実践編と して、これらをテーマにタイトルと前文、本文の構成までを考えて、実 際に書き出してみてください。 機械学習 フロントエンド界隈の技術 職場で実践しているノウハウ(テストやCIなど) 好きなエディタやツール、言語の普及 最近の失敗や障害から学んだ知見
- 41. 40 以下に、日ごろ学んだこととしてありえそうなものを用意してみました。 垂直型、水平型に育ててみて、どんな記事が書けそうか考えてみてくだ さい。 GitでPull Requestを送る手順について学んだ Bootstrapに飽きたので他のCSSフレームワークについて調べた TensorFlowでMNISTに入門してみた 重たいSQLのパフォーマンスチューニングを行った 普段使わない、新しい言語を学んでみた
- 42. 41 Have a Good Writing!