質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
文才の有無に関係なく、誰でもそれなりに整った文章を書くコツ｜村井 弦｜文藝春秋
文章の書き方に正解はない。 ただ、ちょっとした「コツ」みたいなものはあると思う。 僕は会社に入ってから9年間、「週刊文春」と「文藝春秋」の編集部で、文章に携わる仕事をしてきた。 たかだが10年足らずの経歴で何を偉そうに、と思われる方もいるかもしれないが、最近になってようやく、「文章を書くコツみたいなものがあるのではないか？」ということに気がつき始めた。 もちろん一流作家のような芸術的で天才的な文章を書くコツではない。文才の有無は関係なく、誰でもそれなりに整った文章を書くためのコツだ。 noteをやっている人の中には「何かを書きたい、でもどうやったら書けるだろう」と思っている人がいると思う。また、「書きたいんだけど、素人の書いた文章みたいに読まれたら恥ずかしいな」と思って、躊躇している人もいるかもしれない。 さらに、「周りから『何でもいいからとりあえず書いてみたらいい』と勧められるんだけど、
問題解決のための質問群を学んだ - 「考える技術・書く技術」を読んだ - $shibayu36->blog;
最近、自分は問題をうまく分割して解決する能力や、他の人に分かりやすく伝える能力がまだ足りていないと感じていた。そのあたりを強化するために、おすすめと言われた「考える技術・書く技術」を読んだ。 考える技術・書く技術―問題解決力を伸ばすピラミッド原則 作者:バーバラ ミントダイヤモンド社Amazon この本は、わかりやすい文章を作るために、ピラミッド構造で論理構造を作るという技術を教えてくれる本だ。この本を読み終わって、ピラミッド構造を作るという考え方は、問題を分割するということにも、文章を他の人に伝わるように分かりやすく書くということにも応用できる、非常に有用な考え方であると感じた。 まず最初にぱらぱら読んでいた感想は、非常に良いことが書かれてそうなのだけど、なぜか頭に入ってこないということだった。このためあまり面白くないなと思いながら、気になるところを付箋はったりメモしたりしながら読んでい
Slackで簡単チェック！textlint で始める文字校正Bot - コネヒト開発者ブログ
こんにちは！ 新オフィスに移転してから毎日2缶ドクターペッパーを買うのが習慣化してきた @fortkle です。 今回はSlackで簡単に文字校正ができるBotを作ってみたのでご紹介したいと思います。 手軽に校正したい メールやチャットだけでなく、こういったブログやissueに書く仕様など「文章を書く」シーンはたくさんあると思います。 そんなとき自分が伝えたいことを相手にちゃんと伝えることができれば良いのですが、良い文章を書くのはなかなか難しく、今も試行錯誤しています。 そこで、相手に伝えたいことがちゃんと伝わる良い文章を書くためにSlack上で簡単に試せる文字校正Botを作ってみました。 成果物 実際に見たほうが早いと思うので画像を交えてご紹介します。 例として以下の文章をチェックしてみたいと思います。 この文章はご存知の通り、ダミーテキストです ヽ(^o^)丿 そして、様々な、ｴﾗｰﾁ
RedPen でわかりやすい技術文書を書こう | DevelopersIO
最近はブログを始めマニュアルや仕様書など技術文書を書く機会が多くなってきました。 技術文書はわかりやすさが重要だと思うのですが実際は書けていません。 どうしたらわかりやすい文書が書けるのだろうか？と調べていたら RedPen というツールを見つけたので早速試してみました。 RedPen とは？ RedPen とはプログラマや記者が規約に従って文書を記述するのをサポートしてくれるオープンソースのソフトウェアツールです。 プログラミングが規約に従ってコーディングされているかチェックするように、RedPen は自然言語で記述された入力文書の検査を自動化してくれます。 RedPen の特徴 設定が柔軟に行えます。（カスタマイズも柔軟） どのような言語で書かれた文書でも処理できます。（もちろん日本語も OK です） Markdown や Textile フォーマットで記述された文書をそのまま検査でき
初心者でも今すぐできる！読まれる文章の書き方12のコツ - 自分を変える、人生を変える！
2013-02-02 初心者でも今すぐできる！読まれる文章の書き方12のコツ 文章術 一昔前と比べて、私たちが文章を書く機会は圧倒的に増えました。 ネットが普及し、個人が「情報発信の場」を持つのが当たり前になったからです。 ブログやmixi、ツイッター、フェイスブックなどをやっていれば、必ず文章を書くことになります。しかし自分の文章がなかなか読まれなかったりうまく伝わらなかったりして、悩んでいる方もいると思います。そこで今回は「読まれる文章の書き方12のコツ」をご紹介したいと思います。 高等技術を省き、できるだけ文章初心者の方でもすぐ使えるようなコツに絞ってまとめました。 1. 「何を伝えたいのか？」を1つに決める 文章には必ず「それを書く目的」があります。 目的をハッキリさせておかないと、途中で「あれ、えーと何が言いたかったんだっけ？」と迷路に迷い込んでしまいます。 そのよう
サービス終了のお知らせ - NAVER まとめ
サービス終了のお知らせ NAVERまとめは2020年9月30日をもちましてサービス終了いたしました。 約11年間、NAVERまとめをご利用・ご愛顧いただき誠にありがとうございました。
論文作成の技法part1～論文の構造 - プログラマの思索
「勝つための論文の書き方」「創造的論文の書き方」「これから論文を書く若者のために」を読んでみて、論文作成の技法をまとめたみた。 但し、僕は優れた学術論文を書いた経験はないので、想像の部分がある。 ラフなメモ書き。 【元ネタ】 われわれはどのように論文を書いているか（1/12）: 主体性確立のための「弁証法・認識論」講義 われわれはどのように論文を書いているか（2/12）: 主体性確立のための「弁証法・認識論」講義 われわれはどのように論文を書いているか（3/12）: 主体性確立のための「弁証法・認識論」講義 われわれはどのように論文を書いているか（4/12）: 主体性確立のための「弁証法・認識論」講義 われわれはどのように論文を書いているか（5/12）: 主体性確立のための「弁証法・認識論」講義 われわれはどのように論文を書いているか（6/12）: 主体性確立のための「弁証法・認識論」講義
文章に向いてない構造をいかに文章に向いた構造に直列化するかが大事 - きしだのHatena
Software Design 12月号の特集が「なぜエンジニアは文章が下手なのか？」というタイトルだったので、読んでみたら、ちょっと残念な内容だった。 「それは文章で書くべき情報なのか」という章があって、直列化した論理構造であれば文章には書きやすいけど、分岐やループがあるような構造だと書きにくいということが書いてあった。そこで文章化しにくい構造の例として地図があげてあって、暗にそういう構造は文章化をやめて図であらわせと言っているように読める。 けれども、図に書いたところで、書く側は文章化から逃げれて満足かもしれないけど、それを読み取る側は結局どこかから順番に解釈していく必要がある。図に逃げるのは、読み手に責任を押し付けているだけだと思う。 で、「ですから文章を書く前にまず論理構造を考える必要があります」と続いていて、では考えた論理構造が「文章に向かない論理構造」だったらどうするの？逃げる
Webサイトで全角英数字ではなく、半角英数字を採用する理由
Webで文章を掲載する際、英数字は半角表記で統一するのが「常識」です。ですが、なぜ全角英数字はダメで半角英数字に統一するべきなのでしょう。改めて聞かれるとついつい「そういうものだから」と答えてしまいがちではないですか？ また、検索してみても、ちゃんとまとめられた記事がなかなか見つけられません。ということで、全角英数字ではなく、半角英数字を採用する理由をまとめてみました。 ※本記事は技術的な検証が十分に行われておらず、誤った情報である可能性があります。あらかじめご了承ください。 全角英数字は再利用性できません たとえば、電話番号やURLが全角で表記されていると、Office製品やメーラーでリンクとして認識されません。ブラウザのアドレスバーにコピーアンドペーストしても開けず大変不便です。 全角英数字は禁則処理が行われません ブラウザでは英単語が途中で改行されないよう折り返しが行われます（禁則処
わかりやすい文章の10大原則
この記事では、LINEグループに招待できない・参加できない時の対処法や原因についてお伝えしていきたいと思う。 複数人で連絡を行う際にLINEのグループ機能は非常に役に立つ。学校でも職場でも利用されている事が多く、グループ内通話も出来るので簡単な打ち合わせ程度であれば、LINEでも可能になった。 グループの作り方も非常に簡単。 しかし、なぜか相手に招待が届かない…といったことも度々ある。 では、この招待が届かない時によくある原因について見ていこう。 LINEグループに招待できない時の対処法・原因 基本的に以下の場合は、相手に招待を送っても届かない。 既にLINEを退会している(アカウントを変更している)場合 既に招待を送っている場合 相手にブロックされている場合 もしくは、招待しているけれど参加されない…といった場合は、相手側が参加を拒否している可能性もある。 上記の3点に当てはまらない場合
要約のコツを教えてくれるPDF見つけたよ: うらおもて人生感。
・要約のすすめ 読売新聞の記者代ゼミの国語科の土生さんが書いた要約のコツ。非常に読みやすい。 ※矢吹さん、訂正のご指摘ありがとうございます。 ・要約の基礎徹底 38ページもある徹底した要約講義。 軽妙な語り口でホイホイ読めちゃいます。ばっちり演習問題もある親切設計。 無料でこのクオリティは驚きの一言。 ※PDFに直リンしているので、ご注意を。 ＋0723 追記 7/22に「要約の基礎徹底」の著者、矢吹芳裕さんがツイッターで当記事をご紹介いただきました。ありがとうございます。 感謝を込めて、ここで矢吹さんの運営されているブログとwikiをご紹介します。 こちらも要約、ひいては文章書きにヒントを与えてくれる内容です。おすすめ。 僕は昨日と今日で、Garbage Out!!とwikiは読んじゃいました。すぐに読めちゃう筆致がプロい。 ・Garbage Out!! 広く文章の書き方を教え考えさせて
良質なブログ記事を３０分で書き上げるために実践している１０のコト
ユーザーに届ける価値を徹底的に追求する マーケティングを提供します © Copyright 2022 バズ部. All rights reserved. ブログが大事だということは分かっていても、書き続けるだけのネタがない。ネタがあったとしても読者さんの役に立つものを書こうとすると３時間もかかってしまう・・・。 実は、そうした悩みはちょっとした習慣を心がけることで簡単に解消することができる。 そこで本日は、私が短時間でブログ記事を書き上げるために実践している１０のコトをご紹介する。 １．アイデアのリストを作る友人や同僚と話をしている時、電車の中吊り広告を眺めている時、雑誌を立ち読みしている時など、ブログのアイデアは、いつも突然湧いてくる。そうやって、湧いてくるアイデアを忘れずに記録するために専用のノートを用意しよう。 手書きのノートでなくても、Ever Noteを使うと便利だ。『Evern
サービス終了のお知らせ - NAVER まとめ
サービス終了のお知らせ NAVERまとめは2020年9月30日をもちましてサービス終了いたしました。 約11年間、NAVERまとめをご利用・ご愛顧いただき誠にありがとうございました。
ピクサーに学ぶ！人を魅了するストーリーライティングの２２のルール
ユーザーに届ける価値を徹底的に追求する マーケティングを提供します © Copyright 2022 バズ部. All rights reserved. 文章で人を魅了する最も効果的なテクニックの一つがストーリーライティングだ。 いや、文章に限らず、会話でもスピーチでも、人から共感してもらうためには、ストーリーの力を無視することはできない。 ストーリーライティングは、私自身、今最も身につけたいと思っているライティングスキルの一つで、情報収集をしていたところ、『トイストーリー』などで有名なピクサーのストーリーライティングの２２のルールを見つけたのでシェアさせて頂く。 The Pixar Touch ” Pixar Story Rules “ １．成功ではなく挑戦にフォーカスする 主人公の成功という部分ではなく、諦めずに挑戦し続けるという部分を賞賛すること ２．自分ではなく読者が求めているもの
文章を書く人に読んでもらいたい本10冊【NAVERまとめ】 | ひらめき箱
さらっと眺めただけでも琴線に触れる本が多かったので、 自分メモ用もかねてご紹介。（はてブは元記事推奨） NAVERまとめ「ブログに貼る」機能により貼り付け。 記事が自動展開されない場合は以下のリンクをクリック↓
SEが苦手にしがちなドキュメント力を強化する5つの視点
SEに最も必要なスキルは「伝える力」だと言われています。分業が前提となるシステム開発において、意志の伝達がうまく出来ないことは致命的だからです。 よって、作成するドキュメントにも正しく伝える技術が求められるのですが、しかし多くのSEはドキュメント作成を苦手としているようです。 そこで今日は、SEがドキュメント作成で失敗しがちなポイントと、ドキュメント力を強化するための5つの視点について、『エンジニアのための文章術再入門講座』からご紹介します。 1.SEがドキュメント作成で失敗しがちなポイント SEがドキュメント作成に失敗しがちなポイントは、主に以下の2つです。 相手の関心と不一致 知識差のための説明が不足 例えば、システム開発プロジェクトの部長向けの進捗報告の場面を思い浮かべてください。性格にもよりますが、一般に部長クラスの方が気にするのは「予算を超過しないか」「顧客との関係は良好か」「今
文書品質の向上と文書作成時間の短縮：｢考えが文にまとまらない」を解決するためのテクニカルライティング
<BODY BGCOLOR="#ffffff" LINK="#ffffff" VLINK="#ffffff" ALINK="#ebc83d"> <P> <IMG SRC="fig-t8a/gb-bar-introduction.gif" ALT="テクニカルライティングの効果" ALIGN=bottom width="540" height="26"><BR> <IMG SRC="fig-t8a/tw8a-ttl.gif" ALT="文書品質の向上と文書作成時間の短縮" ALIGN=bottom width="570" height="150"><HR> <H1 style="line-height: 150%"><span style="font-weight: 400; letter-spacing: -1pt"> ｢<font color="#800000">考えが文にまとまらない<
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
技術文書を書く際の、心技体
http://www.web-rider.jp/matsuo/%E5%A3%B2%E3%82%8A%E4%B8%8A%E3%81%92%E3%81%8C%E5%8A%87%E7%9A%84%E3%81%AB%E6%94%B9%E5%96%84%E3%81%99%E3%82%8B%E5%A3%B2%E3%82%8C%E3%82%8B%E6%96%87%E7%AB%A0%E3%81%AE%E6%9B%B8%E3%81%8D%E6%96%B9/