ドキュメントを書くときの「メンタルモデルの原則」 - クックパッド開発者ブログ
こんにちは。クリエイション開発部の丸山@h13i32maruです。 みなさんドキュメント書いてますか？私はドキュメントを書くのは結構好きです。最近もプライベートで開発しているJasperというGitHub用Issueリーダーのユーザ向けドキュメント（マニュアル）を書きました。でも良いドキュメントを書くのって難しいですよね。 そこで、本記事では「ツールやライブラリなどを対象にしたユーザ向けドキュメント」を書くときに私が考える原則を紹介します。ちなみに私はテクニカルライティングの専門家ではなく、普通のソフトウェアエンジニアです。そのあたりはいい感じに汲み取っていただけると🙏 🕵️メンタルモデルの原則 良いドキュメントとはどのようなものなのでしょうか？私は「そのツールやライブラリに対して読者がメンタルモデルを構築できる」のが良いドキュメントだと考えています。これを「メンタルモデルの原則」と呼
赤ちゃんを風呂に入れたら泣きやがったので全否定してやる - やまもといちろうBLOG（ブログ）
風呂場で泣かれるとサラウンドで聴こえるんだ、泣き声が。 プロから教わる、良い文章を紡ぐ5つの珠玉のテクニック http://www.lifehacker.jp/2009/10/091005writingtips5.html [引用]1. 使い古された言葉ではなく"自分の言葉で"書く 使い古されようが口語のクセだろうが、紡いでるのは言葉であることに変わりない。使い古された表現でも組み立て方によっては充分読ませる文章ぐらい書けるんじゃないの。むしろ、この引用記事のように、ライフハックという構成というか読ませ方のフォーマットがあれば、つまらない文章でもアクセス数ぐらいは稼げるだろ。本にして売れるかはまた別だが。 [引用]2. 名詞を使う時はよく吟味すること 吟味して書いたことはほとんどないな。むしろ、意識しないで使う名詞から文章を組み立てたほうが、よほどすっきりする。あとで読み返して校正かけるよ
情報処理学会論文誌 校正 - FreeStyleWiki
Real-World -> Real-world にて ＞ で 回答＞解答 挙げ＞あげ 行なう＞行う 全て＞すべて おもに＞主に 第２章＞２章 Fig Caption in English 最後に . (dot) 例えば＞たとえば 受けとる＞受け取る 机の上に拡げる＞広げる 支援する上では＞うえでは 既に＞すでに 書換えによる＞書き換えによる 書込み＞書き込み （校正者によって揺れがある） 呼出し＞呼び出し （校正者によって揺れがある） みなし＞見なし 行なった＞行った 以下の通り＞以下のとおり 共に＞ともに おもしろい＞面白い わかった＞分かった （校正者によって揺れがある） 表の縦罫線トル Proceedings of the > Proc. 伴う>ともなう 拡張した上で>拡張したうえで メニュー等の>メニューなどの 無い>ない 有り＞あり 事が多い>ことが多い 例えば＞たとえば 〜
「ヒット・エンド・ラン」を知らない子供たち：日経ビジネスオンライン
「全員野球で」 と、鳩山由起夫氏は、党代表に就任した折、第一声で、確か、そう言っていた。 その時、テレビの画面を見ながら、わりと簡単に納得した気分になったのは、たぶん私がオッサンだからだと思う。 男でも中高年でもない、日本人のうちの四分の一ほどを占めるヤングでフレッシュな人々は、鳩山代表の発言をうまく理解することができなかったはずだ。 「なぜ野球？」 「野球って、もともと全員でやるもんじゃないのか？」 「メンバー制の秘密地下野球とか、そういう歴史があるんだろうか」 「それよりどうして政治家が野球なんかやるの？」 「党首が投手で捕手が保守とか、そういうシャレみたいなことか？」 まるで違う。 そんな話ではない。 「全員野球」という言い回しは、野球という競技について一定の知識と観察眼を持っている人間でないと正確には理解できない。 その意味で、鳩山氏の演説は、平成の一般国民に向けたメッセージとして
わかりやすい技術文章の書き方
誰が読むのか。 読み手にどんな感想を持ってもらいたいか。 読み手はどれくらいの予備知識を持っているか。 読み手はどんな目的で、何を期待して読むのか。 読み手が真っ先に知りたいことは何か。 レポート・論文とは何か 問いが与えられ、または自分が問いを提起し、 その問題に対して明確な答えを与え、 その主張を論理的に裏付けるための事実・理論的な根拠を提示して、主張を論証する。 標準的な構成要素とは何か レポート・論文の構成は、 概要 序論 本論 論議 という要素が標準的である。次にそれぞれの要素について簡単に見てみる。 概要 論文全体を結論も含めて、すべて要約する。 序論 本論で取り上げる内容は何か。 その問題をどんな動機で取り上げたのか。 その問題の背景は何か。 その問題についてどんなアプローチを取ったのか。 本論 調査・研究の方法・結論 論議 自己の議論・結論を客観的・第三者的に評価する。 そ
はてなブログ | 無料ブログを作成しよう
来年も作りたい！ふきのとう料理を満喫した 2024年春の記録 春は自炊が楽しい季節 1年の中で最も自炊が楽しい季節は春だと思う。スーパーの棚にやわらかな色合いの野菜が並ぶと自然とこころが弾む。 中でもときめくのは山菜だ。早いと2月下旬ごろから並び始めるそれは、タラの芽、ふきのとうと続き、桜の頃にはうるい、ウド、こ…
Life is beautiful: 「ブログは始めてみたいが、何を書いてよいのか分からない」と悩んでいる人のための三冊
私の「CGMの面白さは自ら情報を発信する側にならなければ理解できない」という言葉にもかかわらず、「ブログは始めてみたいが、何を書いてよいのか分からない」とグズグズしている人たちが私のまわりにも何人もいる。今日はそんな彼らのための推薦図書三冊。 ・頭の良くなる短い短い文章術 ブログを書き始めようかと迷っている人の背中をそっと押してくれる良書。自分のまわりの人やものを常に好奇心であふれた眼で見る気持ちさえ持って生きてさえいれば、ネタに困ることなど決してないのだ。ブログの更新が滞りがちな人にもお薦め。 ・理科系の作文技術 それまでは「自分は作文が不得意だ」と思い込んでいた私を一気に開眼させてくれた良書。初めて読んだ時の感想は、「なんで学校ではこんな簡単なことを教えてくれなかったんだ！」である。私が常に「分かりやすい文章」を書くように心がけているのはこの本の影響。 ・文章表現、４００字からのレッス
効率的に校正するための10のコツ | ライフハッカー・ジャパン
ライフハッカー過去記事「プロアマ問わずライターさん必読、スランプから脱出する5つのコツ」ではライティングのコツをご紹介しましたが、今回はその続編。誤字脱字やタイプミスを減らすための校正のコツについてご紹介します。 ライター向け情報ブログ「Ghostwriter Dad」では、校正スキルを上げるためのコツとして、以下の10点を紹介しています。 1. 一呼吸おいてから編集にとりかかる 下書きを書いたら、編集・校正作業まで少し時間をおこう。最低1時間、できれば1日程度空けるとよい。下書きと編集との間をとると、自分の下書きを客観的にチェックしやすくなり、ミスにも気づける。 2. 文をシャープにしよう 最終稿は下書きの10%減が目安。重複した表現を避け、無駄な言葉を取り除こう。 3. 静かな環境でやる 校正には正確性が求められる。編集作業をするときは、気が散らないような静かな環境で集中してやろう。
アラン・ケイ - 「ソフトウェア工学」は矛盾語法か？ [邦訳]
アラン・ケイ Is “Software Engineering” an Oxymoron? By Alan Kay (訳注: 以下の文章は、http://d.hatena.ne.jp/sumim/20080806/p1 に紹介されていたアラン・ケイの文章 -- Is “Software Engineering” an Oxymoron? -- を訳したものです。原文もsumim さんのサイトからダウンロードしました。最初に書かれたのは 1999年から2000年ごろと少し古いので注意してください。日本語で矛盾語法(oxymoron)とは聞き慣れない言葉ですが、ジーニアス英和大辞典によると an open secret (公然の秘密) や、living death (生き地獄) のような矛盾する二つの単語を組み合わせた熟語の事を言うらしいです。) 真のソフトウェア工学はまだ未来のものだ。一年と
開発工程でSEが書く文書の基本 − ＠IT自分戦略研究所
「提案書」や「要件定義書」は書くのが難しい。読む人がITの専門家ではないからだ。専門用語を使わず、高度な内容を的確に伝えるにはどうすればいいか。「提案書」「要件定義書」の書き方を通じて、「誰にでも伝わる」文章術を伝授する。 SEはさまざまな文書を作成する必要があります。その中でも、提案書や要件定義書の作成に悩むSEは多いようです。なぜなら、これらは「顧客に読んでもらわなければならない文書」だからです。 本連載では、「誰にでも分かる」提案書や要件定義書を作成するための文章術を解説します。ただし、分かりやすい文書を作成するには、文章術だけでは十分ではありません。必要な情報を顧客から引き出すためのコミュニケーション、文書全体の構成も重要です。 第1回では、SEが作成する文書はどのようなものかを概観します。第2回では、情報を引き出すための顧客とのコミュニケーションのポイントを説明します。第3、4回
ベンチャー企業の経営危機データベース（METI/経済産業省）
多くのベンチャー企業が起業後に、同じような失敗、トラブル、ヒヤリとした経験をしており、成長に伸び悩む企業が多いと言われています。そこで、ベンチャー企業の経営者が様々な場面で決断を下す際の「転ばぬ先の杖」として、将来起こりうるリスクを予見できるような失敗、トラブル、ヒヤリとした経験の事例を収集・データベース化しました。ベンチャー企業の成長に向けた経営判断の材料としてご利用いただければ幸甚に存じます。 本データベースには、平成19年度にベンチャー企業にインタビュー調査を実施して収集した83の失敗、トラブル、ヒヤリとした経験に関する事例を掲載しています。事例は、ベンチャー企業の成長ステージや失敗、トラブル、ヒヤリとした経験の原因及び結果といった分類項目をもとに検索が可能となっています。
第13回 その文書、主語はいったい誰なのか？：日経ビジネスオンライン
「仕事で書く文章は、 どうしてこんなに、妙な感じになるんだろう？」 そう感じている人はいないだろうか？ 家族や友人にプライベートでメールを書くのは さして苦ではない人も、 「自分は学生時代、けっこうよく文章を書いていた」 という人も、 仕事の文章となると、自分で書いていながらも、 自分で首をひねるような、妙な文章になることがある。 とくに、まったく一面識もない、初めての人に、 依頼の文章を書くときなど、 恐ろしく時間がかかってしまい、 「自分はこんなに書くのが遅い人間ではなかったはずだ」 と自分を疑いたくなることもある。 仕事の文章では、なぜ普段の調子がでないのだろう？ 私も、企業に勤めていたある日、 次年度の企画書を書いていて思った。 「企画書って、なんでこんなに書きづらいんだろう？ 内容に頭を悩ませているのはもちろんだけど、 それ以前のところで、いちいち時間をとられている感じがする。
1
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
パスワード認証
Nurse's SOUL: 論文の書き方、研究（学会）発表のしかた