サクサク読めて、
アプリ限定の機能も多数！
アプリで開く
howto-tech-docs.md技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近はAmazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ本番環境に変更を加えるにあたっての包括的な情報や具体
社内向けの教育資料を、ど素人でもわかるようにと思いながら作っていて、じゃあ「わかりやすい」って何だろうって考えてた。今まで読んできたいろんなわかりやすかった本とそうでない本を思い浮かべながら、一般的にここを注意すればわかりやすさを確保できるだろうっていうポイントを一旦まとめておこうと思った。そうしてまとめてみると、本に限らず人に何かを伝えること一般に適用される話だなと思った。 読む側の負担を減らす わからない＝理解をはばむ障害物がある。この障害物を取り除く／回避する作業が「わかる」ために必要になる。その作業を、作者ではなく読者が負担するとき「わかりにくい」本になる。 日本社会だと情報の受け手の側がこの「わかる」ための作業を負うことでコミュニケーションを成立させる傾向にある。空気を読むというようなことだ。そのため発信者側が事前に手を尽くしてわかりやすく発信するというのが苦手で、相手が汲み取っ
オペレーション部 江口です。 先日、社内でビジネスライティングについてオンラインで講義する機会があったので、その資料を公開しておきたいと思います。 いわゆる技術文書というよりは、メールやSlackなど、相手とやり取りを行う際の文章作成を主に考えた資料となっていますので、その点ご承知おきください。 背景 講義を行ったのは、アカウント周りの作業を行うアカウントチームに対してでした。チームの業務内でメールでの顧客とのやり取りやSlackでの社内でのコミュニケーションなど、文章を作成する機会が多く、その際の書き方に課題を感じている方が多いようだったので、少しでも助けになればと思いこの講座を企画しました。 私は別に人に自慢できるほど文章がうまいわけではないですが、約20年のエンジニアのキャリアで顧客とのやり取りや技術文書の作成などをそこそこの数こなしてきました。先輩や上司などからいろいろな指摘を貰い
創作論とか小説の書き方みたいな本について言うと、作家やその周辺の人が書いているせいか、かつてはその困難さを前面に掲げて、結果的に創作行為の神秘性を保守する手合が多かった。 近頃は「誰でも書ける」みたいなのも随分増えたけれど、タイトルだけ付け間違えたようなのが多くて、あいかわらず、もったいぶった文士臭さが抜けてない。 探す場所を間違えたのだと考え、はなっから「創作行為の神秘性」なんて受け付けない人たち向けに書かれたものを探した。つまり子供向けである。 学校の課題になったりするせいか、アメリカのものに、手続きだけに注力した実にアッケラカンとしたのが多かった。 ネットでフリーで手に入るものだと、National Novel Writing Month（通称：NaNoWriMo ※）のYoung Writers Program用ワークブックが、ほぼ同じ手続きを小・中・高校生向けの３種類に書き分けて
NEWS 書籍『数学文章作法』が刊行！ お知らせ：現在「文章教室」のコーナーはお休み中です。 自分の練習として投稿してくださってもかまいませんが、 添削などのお返事はできません。ご了承ください。 目次 はじめに 「文章教室」の目的 想定している参加者 「投稿の前に」と「投稿のテンプレート」 文章教室 第1回 文を短くしましょう 第2回 適切な単語を選びましょう 第3回 パラレリズムを使いましょう 第4回 自然な順序で書きましょう 第5回 語順を変えてみましょう 第6回 重要点は2回書きましょう 第7回 よい比喩を使いましょう 第8回 まずはどんどん書きましょう 第9回 接続詞をうまく使いましょう (解答編公開中) 第10回 ストレートに書きましょう (問題編公開中) 第12回まで続く予定です… みなさんからの声 ぜひ、感想をお送りください 関連リンク 参考書 投稿者のページ 解答者のページ
分野問わずに遅くとも大学3年生の7月までには読むべき本。これを読んでおくとばらばらに学ぶであろうエントリーシート、小論文、卒業論文の作成技術を統合できる。 三森ゆりか著：大学生・社会人のための言語技術トレーニング 著者の三森ゆりかさんがつくば言語技術教育研究所で言語技術の普及を始めた背景が本書の「はじめに」に書いてある。 私は父の仕事の都合で、13歳から17歳までの4年間を当時の西ドイツの首都ボンで過ごしました。そこで、私は、各国の外交官や新聞記者の子弟の受け入れ指定校だったドイツの中高一貫校に入り、1年間外国人のためのドイツ語の授業を受けた後、年齢相応のドイツ人のクラスに放り込まれました。中学3年生のクラスでした。そこでの授業は全て議論中心で、議論後は必ず小論文の提出が義務付けられていました。私がまず直面した問題は、ある程度ドイツ語ができるようになっても、議論に参加できないことでした。
目次 はじめに 読者に対する心がけ 誰がその文章を読むのかを考えよう 読者は何を知っているかを考えよう 読者がどんな感じを受けるかを考えよう 読者と対話する気持ちになろう 自分に対する心がけ 書こうとせず、読もうとしよう 読もうとせず、読みはじめようとしよう 何でも書いていいんだよ 惜しげなく人に与えよう 人からのものには敬意を払おう 魔法の呪文は毎回発見しよう まず自分がよく理解しよう 知識を誇るために書くのをやめよう その他の心がけ 言葉についての心がけ 長い文は注意して使おう 書いたものは必ず読み直そう 適切な例を示そう 言い換えの練習をしよう ８割でよしとしよう すべてを動員しよう その他の心がけ 環境についての心がけ 人の「気」を意識しよう 頑丈で軽い文章作成のツールを使おう その他の心がけ 編集者に対する心がけ 助言はよく聞こう 自分の状況を正しく伝えよう 感謝の気持ちを忘れな
1.報告書の構成 報告書とは、上司や関係者に必要な情報を提供するための文書のことです。３層構造（標題→内容要旨→詳細内容）で、情報の整理や要約をしていきます。 例えば、日時、場所、目的、内容等について、情報を簡潔に記入します。 また、所感は記入する場合と、しない場合があります。その場の細かなニュアンスを伝えたほうが有効な場合には、所感も書くようにします。 【報告書（例）】 〔pdf〕打ち合わせ報告書 〔pdf〕営業報告書 1-1.報告書の全体構成 注意すべき点は、以下の三角形の図のように、「標題」は「内容要旨」（打ち合わせ内容）の要約、 「内容要旨」は「詳細内容」（ヒアリング事項等）の要約という３層構造を理解することです。 実際、報告書を上から（標題から）順に書こうとするから難しいのであって、 報告書の説明文（詳細内容から）順に書いていけば、割と楽に書けます。 【報告書の構造（下位にいくほ
このページでは、正確な文章を書くための秘訣をまとめてみようと思います。それほど文章がうまいとはいえない私が、文章の書き方について述べるのですから、むこうみずな行為であることは百も承知です。しかし、数年に渡って探求した正確な文章の書き方が、少しでもみなさんの役に立てばという思いを自分への励ましに代えて筆をとります。 ここでお話するのは、「文章をいかに正確に書くか」や「自分の考えをどうやったら適切に表現できるか」であって、決して「どうやったら人を感動させる名文句が書けるのか」ではありません。 このページを読んだら「科学技術文献」を書くための技術が少しは身に付くのではないかと期待しています。しかし、 人はいさ 心も知らず ふるさとは 花ぞ昔の 香ににほひける (紀貫之) などのような心に残る文章が頭に浮かぶようになるわけではありません。 絵の書き方に例えて言うなら、ここで述べる内容は、色彩や調和
・13日間で「名文」を書けるようになる方法 高橋源一郎の明治大学大学院における「言語表現法」講義の書籍化。全13回の授業が学生とのやりとりを含めて収録されている。とてつもない名講義。言葉で語らず、インタラクションで考えさせるという高度な教授法を、毎回繰り出す。 初日、スーザン・ソンタグの「若い読者へのアドバイス」という名文が配られる。死期が近いことを悟った思想家が若者に向けて「心の傾注」という言葉をキーワードに真摯な忠告を短い手紙のように書きつづったものだが、「読み終わったら、その紙から目を上げ、窓の外を眺めてみてください。なんて美しい風景でしょう。このキャンパスのいいところは、こういうものが見られることです。すぐ横に、そんなに美しいものがあるのに、活字ばかり追いかけてはいけません。読んだものは忘れて、見ることに、傾注してください。」と先生。 オバマ大統領の演説、斉藤茂吉のラブレター、しょ
たとえどんな秀逸なアイディアが自分の中にあったとしても、それを的確に伝える文章力がないと実現は難しいーーそんなふうに考えたことはありませんか？ 昨日行われたライフハッカーのイベント後の雑談で、出演して頂いたパネリストの御一人である杉山竜太郎（株式会社LoiLo/ 取締役）さんは、お子さんの教育について"フリーな方針だよ（笑）"と前置きしつつも、「書くこと」だけはきっちり教えてあげたいと仰っていました。考えてみれば、別に小説家を志すわけでなくとも、メールやら企画書やら、ビジネスにおいて「書く」局面は、今も昔も満載。その傾向はむしろ拍車がかかりそうですから、もっとも有効な"子育てハック"といえるかもしれません。 文章には好みもありますし、文体は人それぞれのパーソナリティーなだけに、よくある文章講座的なものには疑問符をつけたくなります。特に日本語は、その是非はともかく、けっして断定せず、結論を先
日本語の三人称における視点について、例文を使った簡単な考察を。 まずはじめに、母親の泰子（やすこ）さんと息子の竜児（りゅうじ）くんに登場してもらいます。 例として、母親の泰子さんが息子の竜児くんの頭をなでるという動作を三人称で書きます。 泰子は竜児の頭をなでた。 というのが、ごく普通の書き方だと思います。この文章は、視点と関係性を意識して、次のように書くことができます。 1-a 泰子は息子の頭をなでた。 1-b 母は竜児の頭をなでた。 文を足して視点をはっきりさせ、少し手を加えると、以下のようになります。 2-a 泰子たちは公園のベンチに座っていた。泰子は息子の頭をなでた。 2-b 竜児たちは公園のベンチに座っていた。母が竜児の頭をなでた。 aの場合、視点は泰子さんにあります。読み手は、彼女の目を通して、物語を見ることになります。 そして彼女から見れば竜児くんは息子なので、三人称でも竜児く
「形容詞 + です」 は誤用ではない 変な日本語(1) 「危ないですから」-九十九式 電車に乗っていると、ホームでこんなアナウンスがよく流れてくる。 「3番線に電車がまいります。危ないですから、黄色い線の内側にお下がりください」 僕はこれを聞くたびに、強烈な違和感を覚える。電車には毎日乗るので、この襲い来る違和感と戦うだけで会社に着く頃にはヘトヘトになってしまう。 言うまでもなく、「危ない」という形容詞に直接「です」を付けるのは誤用だ。 変な日本語(1) 「危ないですから」-九十九式 「危ないです」 のように、「形容詞 + です」 という表現は、文法的に間違った用法ではない。上記リンク先の主張の根拠として、以下の MSN相談箱の回答欄が引用されているが、これに至ってははっきり 《間違い》 といって良いだろう。 昭和27年の国語審議会で「形容詞＋です」表現を「許容する」としたときから、日本
1リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
処理を実行中です
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
