読みやすいドキュメントを書くために今日からできる7つのこと｜壮｜Masato Tanaka
こんにちは。壮（@sew_sou19）と申します。 メガベンチャー企業でエンジニアとして働いています。 エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。 リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる — 壮 (@sew_sou19) November 28, 2022 そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2
note ――つくる、つながる、とどける。
クリエイターが文章やマンガ、写真、音声を投稿することができ、ユーザーはそのコンテンツを楽しんで応援できるメディアプラットフォームです。だれもが創作を楽しんで続けられるよう、安心できる雰囲気や、多様性を大切にしています。
PREP法とは？相手に伝わるわかりやすい説明の構成【例文つき】
PREP法とは、わかりやすい説明の構成を作るためのモデルです。 もしもあなたが上司から、 「つまり何が言いたいの？」 「結論から言って」 「その根拠はなに？」 「ちゃんと整理してから話して」 なんて言われた経験があれば、ぜひPREP法を身につけましょう。PREP法は汎用的なスキルです。PREP法が身に付くと、上司への報告・部下への指導・プレゼンテーション・商談・インサイドセールスのお電話・ビジネス文書の作成など、「わかりやすい説明」が求められる、あらゆる場面でのコミュニケーションが円滑になります。 PREP法とは、 Point ：要点（結論・主張） Reason ：理由（結論にいたった理由・そう主張する理由） Example：具体例（理由に説得力を持たせるための事例・データ・状況） Point ：要点（結論・主張） の頭文字をとった、わかりやすい説明の構成を表したモデルです。 PREP法を
「なんで『。』じゃなくて『．』を使うの？」 彼氏のメールの「ピリオド」が怖かった漫画がほっこり＆ためになる
※本記事はアフィリエイトプログラムによる収益を得ています 子供でも大人でも、いろんな人との出会いとふれあいがあるもの。たとえば転校生とのはじめての会話、たとえば自分と違う業種の人とのご挨拶。そのとき、相手の言葉や行動に「……それって何か特別な意味が？」みたいに、自分にとってはじめての体験に違和感や不安を抱いたこと、ありませんか？ ことり野デス子さん（@DEATHcotor）が気になってしかたなかったこと。それは付き合っている彼氏さんからのメッセージについてでした。 送られてくるメッセージはいつも、「。」が「．」に、「、」が「，」になっていたのです。見たことのない使い方に、違和感を超えてちょっとした恐怖を感じてしまう、ことり野さん。思い切ってその疑問をぶつけてみました。 ことり野さんのちょっとおびえた顔に驚く彼氏さん。 聞いてみれば「なーんだ！」というか、笑い話ですむような理由。 彼氏さんは
村上春樹の文章は「うまくはないが読みやすい」
https://note.com/historicalmoc/n/n284957b96801 出したな！ 俺の前で！ 村上春樹の文章の話を！ 村上春樹の作品はほぼ読んだので大体同意だけれど、肝心の文章について全く語られていないのは片手落ちとしか言いようがない。こういう何かを語っているようでその内実がわかりにくい言葉を並べるからハルキストだのなんだの揶揄られるんだ。ファンなら真面目にやれ。村上春樹以外の人間が村上春樹の真似したら中身がない駄文にしかならないって小学校で教わらなかったのか。 つーか村上春樹の文章は別にうまくねえから。特徴的で読解大好き人間ほいほいってだけ。 リズムがあり、断定調である（巧くはないが読みやすい）比喩表現を多用し、不思議なモチーフをたくさん取り入れるが、書いてることの中身について説明しないめちゃくちゃはっきりした含意が含まれていることがある（ないこともある）というこ
質の高い技術文書を書く方法 - As a Futurist...
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
父がやってた訳の分からない会社を継いで大失敗した
親がやってるワケわかんない会社を継ぐという話がホッテントリ入りしてて「まんまウチと同じだな」と思ったので書いてみることにした。 うちの父は自宅の一室を事務所として使っていて、社員は父親一人。電話で注文を受けて、同じように注文を出すという只の取次業務を延々とやるだけ。 自分が小さい頃は別に不思議には思わなかったけど、高校生くらいのときは「何か非合法なものを取り扱っているんじゃないの？」と不審に思ったりしたこともあった。 自分は父の跡を継ぐつもりは全くなかったし、父の側にも継がせる気は無かった(多分)。 しかし残念なことに氷河期真っ只中で大学を卒業した自分は全く就職先が決まらず、実家に戻り父の仕事を手伝うことになった。 そしてそこで漸く父の仕事の全容が判明した。 自分の地元は魚の養殖(タイとかハマチとか最近ではマグロとかいろいろ)が盛んで、父は養殖業者向けに養殖用のエサの卸売をしていたのだった
Scrapbox - A new style of team wiki
Effortless ideation.Type brackets around an `[idea]` to create a new link or see auto-complete results. You can instantly click to jump to a new page and keep typing ideas. Compound organization.As you add more pages your ideas get more and more organized. By adding a single link you can see new connections to dozens of related pages. Frictionless focus.Paste links to embed. Share code with syntax
あなたは本当に文章を書くのが遅いのか | おそらくはそれさえも平凡な日々
このエントリーは、Mackerel Advent Calendar 2020 5日目の記事です。 さて、多くの人が「自分は文章を書くのが遅い」と思っているのではないでしょうか。僕もそう思っていました。 ブログエントリーを書き出すと得てして思っていた以上の時間がかかります。書くことがだいたい決まっているちょいネタのつもりであっても書き出してみたら数時間かかってしまう、大作であれば丸一日潰れてしまったり、しばらく寝かして数日がかりになることも珍しくありません。そして「ああ、自分は文章を書くのがなんて遅いのだ」と嘆いてしまうのです。 そして、見事な大作ブログ記事をバンバン投稿している人を見ると「書くのが速い人は羨ましいなー」と羨望してしまいます。また故栗本薫氏が、一時間に原稿用紙96枚分を書いたなどの伝説を聞くに、圧倒されて唖然としてしまい、やる気を失ってしまいそうになります。 しかし果たして本
文章に関わる全ての人のための Git & GitHub 入門 1-3「コミットを理解して活用する」 - Qiita
皆さん、今日もローカルにコミットしてますか？（言いたかっただけ） この連載は（中略）文章を扱う全ての人を対象にしています。 なんとなくで Git を覚えてしまっている人にもたぶん役立ちます。 シリーズ記事一覧 1-1「Git と GitHub を使うメリット」 1-2「コミットを積み上げる」 1-3「コミットを理解して活用する」 1. 今回のゴール コミットってなに？ コミットを書き換えたことにする 過去のコミットの内容を復元する 編集中の内容やステージを取り消す 便利な比較差分ツールの紹介 今回はちょっとしたお勉強と、使えるようになると捗る Tips の紹介です。 Tips はけっこうな頻度で使うので、実際に手を動かして覚えてくださいね。 2. コミットってなに？ 今後、高度な Git 操作を行ううえでは、 Git の仕組みを理解しておくことが何より重要です。 Git の仕組みを理解して
南ことりのスカートの向こう側に、あらゆるプラモデルの本質を見る。 | 超音速備忘録
未組立プラモ写真家。稀に組む。山登る。からぱたへのお問い合わせ、文章・写真・DJ・飲酒のオファーはTwitter @kalapattar からどうぞ
岩本ゼミにおけるレポート・論文の書式の基本ルール｜関大岩本ゼミのアドミン
レポート及び論文では「基本的な能力を有した日本語ユーザーであれば誰でも理解できる（誤解しない）」精確な（＝精密で的確な）日本語を書くことが求められます。その能力を身に付ける第一歩として，以下のルールを必ず守ってください。中には瑣末なモノも含まれますが，これらを守るだけで添削・修正の手間も再提出の可能性も格段に下がります。これらの基本的な書式が守られていないレポートは添削せずに送り返します。 1. 「何となく伝わるだろう」は絶対にNGです。書いてある通りにしか解釈できない，逆に言えば，その他の（拡大）解釈や曲解を許さない厳密な文章を書くことを心がけましょう。 2. そのためにも，まずは主語を明確にすること。「書かなくても伝わるだろう」「好意的に解釈してくれるだろう」という期待を読み手に押し付けてはいけません。 3. 主語を明確にしたら，主語に述語を対応させましょう。主述が対応していないという
プレーンテキスト Markdown 時代の終焉
なぜ Day One は Markdown を捨てたのか Day One が Markdown をやめて WYSIWYG に移行した話は前書いた。 Day One がクソになった Day One 、このブログでも度々言及していて、 Markdown で日記が書けて便利だったんだけど、最近のバージョンアップ（ Mac は 2.8 以降 、 iOS は 3.0 以降）でプレー... portalshit.net 自分が知っている範囲でアンチ Markdown 勢は Scrapbox くらいしか思い浮かばず、 GitHub や Trello などのグローバル勢に加え、 Qiita やはてなブログなど日本国内向けのサービスでも当然のように Markdown が共通言語として使われているのに、その Markdown を捨てて WYSIWYG 化する1という戦略は疑問だった。 ひとむかし前の WYSI
傘をひらいて、空を
仕事やめたんだあ。 友人が言う。皆が一斉に失業保険について質問する。もうやったか。自己都合退職でももらえる。手続きはこう、必要な書類はこう。 その場にいる全員が失業保険の申請をしたことがある、または申請方法を調べたことがあるのだから、就職氷河期世代とはせつないものである。資格職外資大学院入りなおし中途採用公務員、そんなのばかりである。 しかし、五十近くともなると職が落ち着き、転職がぐっと減った。だから仲間うちで仕事を辞めたという話が出るのは久しぶりなのである。 退職したという友人は、失業保険ねえ、とつぶやく。めんどくさい。 皆がいっせいに、もったいない、と言う。もらえもらえと言う。 しかし、よく考えればこの女には昔からそういうところがあるのだ。 彼女はふだんはパワフルだ。早くにできた子どもが二人いて、若くして配偶者を亡くし、親類や友人や、もちろん自分の能力と時間も含め、手持ちのリソースをフ
The Elements of Styleの全訳
『The Elements of Style』の全訳 William Strunk, Jr.著、森田尚 訳 I. 序章 この本は、文章構成の練習と文学の研究とを兼ねた英語のコースで使われることを想定している。この本では、平易な英語のスタイルに関する一番大事な必要条件を、手短に示すつもりだ。この本では、いくつかの本質的要素、つまり最も間違えられることが多い語法のルールおよび文章構成の原則とに（第II章と第III章で）注意力を集中することにより、講師と生徒の負荷を軽減することをねらっている。セクションの番号は原稿を修正する際のリファレンスとして役に立つだろう。 この本は英語のスタイルという分野のほんのわずかの部分をカバーするに過ぎない。だが筆者の経験では、いったん本質的な要素をものにしてしまえば、生徒にとって一番効果が高いのは自分が書いた文章の問題点に基づいて個別指導を受けることであり、講
論理的な文章の書き方｜文章力を簡単に上げるコツをお話しします。 | 弁理士ブログ｜とある士業の知的な日常
僕は、とある法律事務所で働く弁理士🙈 僕は、毎日、特許明細書と呼ばれる法律文書を作成する仕事をしています。 その過程で、論理的な文章を書くスキルを身につけてきました。 そこで今回は、「論理的な文章の書き方」についてお話しします。 この記事を読むメリット この記事を読むメリットは以下のとおりです。 ・論理的な文章の書き方を理解できる。 ・簡単に論理的な文章を書く方法を理解できる。 ・ブログ、記事、レポート、論文などの文章を書く上で応用できる。 目次です 論理的な文章とは 論理的な文章を書くために重要なこと 論理的な文章を書くための文章の構成方法 具体的な文章の書き方（ほうれい線の予防に関する記事） まとめ 論理的な文章とは まず「論理的な文章」とは何でしょうか。「論理的」というのはその用語自体が漠然とした確定しない用語だと思いますのでここで少し補足します。 ここでいう「論理的」というのは「
「作文が書けない子」に本当に必要な訓練の話
先日、東洋経済さんでこんな記事を拝読しました。 ｢作文｣が書けない子に教えたい3つの言葉 文章を書くことは、観察し、驚きを見つけ、考えることです。これがステップ1からステップ3への手順に当てはまるのです。 （東洋経済オンライン） 正直なところ、この記事を書いた方は「作文が書けない子」のレベルをかなり高く見積もっているなあ、と感じました。 いや、文中のテクニック、文中の手法が悪い、というわけではないのです。ここに書かれていることは、それはそれで非常に有用、非常に有効なことだと思います。 「観察→深堀りと整理→考察」という思考法は、あらゆる表現、あらゆる論考で重要な手順です。 小さい頃からこの手順になじんでおくことはとても有益ですし、その際の教え方、かみ砕き方として、文中提示されているような言い方をするのも有効でしょう。そこについては何の文句もないんです。 ただ、ここでいう「作文が書けない子」
「桃が5個あります。3個もらうと全部で何個になりますか」 足し算とも引き算ともとれる算数の問題が難しい
「桃が5個あります。3個もらうと全部で何個になりますか」という、一見簡単そうで解答に困る算数の文章題がTwitterで話題となっています。桃がどこから誰へ移動しているのか、文章が不明瞭でどうとでも解釈できてしまう。 この問題、自分が5個持っているところに、さらに3個もらったとして、「5＋3＝8」で「桃は全部で8個」と答えさせたいように見えます。しかし、どこかに5個ある桃を3個取ったとすれば、もともとの桃は5－3で2個になるとも読めます。文章としては「どこかから3個もらったのだから、手元にある桃は全部で3個」「5個あるうちの3個が移動しようと、桃は全部で5個」といった解釈もでき、考えるほどに正解が分からなくなってきます。 問題文は投稿主のゆき乃（@yukiNoy）さんが、小学1年生の息子さんと解いたドリルを紹介したもの。息子さんは「もともと5個ある桃は誰のなの？」と困惑しながら、どこかに5個
就活つらい
なんの捻りもないタイトルしか思い付かなかった。 それほどまでに私は疲れてる。疲れきってる。 明日締め切りのESを半分書いたところで手が止まってしまった。 何も文章が出てこなくなったから。 質問に対して自分の正直な考えと、就活本に書いてあるセオリーとを照らし合わせて、正解の文章を考えようとしても、何も浮かばなくなってしまった。 考えれば考えるほどこの企業の志望度は高くなっていき、同時に書けなくなっていく。 ひどいジレンマである。 私には夢があった。 夢を叶えたくて就活を頑張った。 正確には頑張りたい、と思った。 でも次々と志望業界の企業が落ちていく中で、根本的に自分は向いていないのだと気づいた。 それどころか、1mmの努力も出来ない自分がいたことに気づいた。 夢破れた私を横目に、友人たちは次々に内定を獲得していく。 私はコミュニケーションに難があるわけではない。 バイトで接客業もやってて評判
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
◆一部マスコミへの抗議のための「積極的断筆」／ホームページ、SNSの中止について | 八王子市議会議員 佐藤あずさのホームページ
