相手に誠実に、わかりやすい文章を書くための心がけをまとめました。 どういう思考プロセスからどんな表現が生まれるのか、参考として実例を紹介しています。実際に読み比べ、SmartHRの従業員として何かを伝えようとするときの、参考にしてください。 伝わる文章のガイドライン何を伝えるかによって、必要な情報の量や説明の粒度は異なります。 情報が不足していたり、逆に情報が多すぎたりすると、読者が意図を読み取れないことがあります。 読み手となる相手の状況（読む場面、事前知識など）を踏まえ、言葉にする内容や表現を厳選することが大切です。 目的に合わせて情報を取捨選択する読者の目線に立ち、コンテンツの目的に合わせて情報を取捨選択しましょう。 実例1：法律や業務に関わる記事目的業務に関係する「厚生年金保険」について正確に知りたいと思っている人に、わかりやすく内容を伝える。 Before日本の年金制度は、全国民

概要自分への備忘録用に書いておく。 すべてにとって共通して言えることは、「なぜ難しく感じるのか」という点と、「どう突破するのか」という点だ。 この2点に集約される。 自分がバカだから文章が難しいわけではない難しい文章を読むのは、誰にとっても難しい。 もちろん、ある人にとっては難しい文章が、別のある人にとっては簡単だというのはよくある。ただそれは、前提知識の違いや読み方の違い、たまたまその人の感性が筆者の感性にフィットしている場合や、筆者に対してどのぐらい信頼感を抱いているかにもよる。もしそこに差がなければ、同じ難しさになるはずだ。 つまり、もし自分と似通った能力を持っている人がその難しい文章を読めば、必ず難しいと感じるはずだ。 思考実験として、自分という人間をコピーしたあと、その文章の読解に必要な能力だけはそのままにして、さまざまな性格・さまざまな外見・さまざまな人生経験・さまざまな年齢に

Deleted articles cannot be recovered. Draft of this article would be also deleted. Are you sure you want to delete this article? はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと（テクニカルライティングとも言います）は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「テクニカルライティング」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。 もしこのテクニカルライティングの原理原則をまだ体系的に学習し

西村マサヤ @masayaquality 今日、違う部署の新卒から「わかりやすい文章を書く方法を教えて欲しい」と言われたので、このリストを送ったのだけど、ほんとこの20個意識するだけでだいぶ変わると思うな。 新卒や学生はぜひ実践してみてほしい。 pic.twitter.com/JrUgbpmD53 2020-05-26 22:50:51

いまちょうど『文章力が、最強の武器である。』という本を読み終えたところです。 これで、ついに出そろいました。 長らく追い求めていた「文章力」の理想郷。 どうやらそこには、4人（冊）の四天王がいらっしゃったようです。 これまで「文章力」「文章術」「書き方」と検索して、約20冊近く読んできました。 その中から選び抜かれた四天王をご紹介します。 入門編『文章力が、最強の武器である。』藤吉 豊 https://amzn.to/3njBbiF 最初に四天王の1人目、入門編で待ち構えているのがこの『文章力が、最強の武器である。』。 まず何と言っても、章立てがすごく魅力的なんですよね。 第1章は、文章力が劇的に上がる「3つの視点」。 おもしろい わかりやすい 読みやすい この3拍子が揃った文章こそが、「良い文章」なのだと筆者は語っています。 その後、先ほどの3拍子それぞれを伸ばしていくための考え方・型・

howto-tech-docs.md 技術文書の書き方 このメモは、私（@ymmt2005）が長年にわたってソフトウェアプロダクト開発に関わってきて 2022年現在こうしたほうが良いと考えているベストプラクティスです。 科学的な分析等に基づくわけではない経験則であるため、今後も随時見直すことがありますし、 ここに書いてあることが常に正しいわけでもあらゆるソフトウェア開発に適するわけでもありません。 しかしながら、実務経験が豊富で、モダンな技術スタックに明るいエンジニアの経験則は一定の 役に立つのではないかと考えて記します。 技術文書とは ここでは、ソフトウェア開発で技術者が書くべき文書ということにします。 ソフトウェアエンジニアにも役割がいろいろあり、アーキテクトと independent contributor では書く文書が違うということはあるでしょうけれど、ここではごっちゃにします。

と思っている話です。もはやタイトルでぜんぶ言ってしまった。 せっかくなのでもう少し続けます。 2020/05/03追記：第二弾？書きました この本がまだ初稿になる前、共著者のみなさんと執筆真っ最中の頃に何度か打ち合わせがあったのですが、そこで「書籍的な文章を書き慣れてない人って、"という"と"こと/もの"を多用しがちなので、この2つを抑えるだけでも文章がシュッとするんですよ」とお話したら思ったより反応があったので、これは需要があるんじゃないかと感じたのがきっかけです。 ここから先は具体例を交えて解説していきます。 さすがに他人様のテキストを使うのは気が引けるので自分が書いた記事を例に挙げます。……でも自分はこのテクニックを使うようにしているので、該当する記事がなかなかないんですよねぇ……と思ったらあった！ （よりによってこれか……せっかくなので皆さんスタァライトを観ましょう！） 記事中では

ウェブ制作や開発の仕事で文章を扱う機会は多いはず。書き手は不自然に思っていない文章でも、読み手は違和感をもっていることがあります。文章校正テクニックを覚えるだけでおかしな表現は少なくなり、読みやすい文章を書けるようになります。 本記事では、ICS MEDIAで実践している文章校正の一例を紹介します。 レベル1、基本的な校正ルールを使う いろんな場面で使える基本的な文章校正テクニックから紹介します。 テクノロジー系の名詞は正しく記載しているか テクノロジー系の名詞を間違って使うと、「本当に技術に詳しいの？」と読者からの信頼度が下がります。名詞は大文字小文字、スペース有無含めて正確に記述しましょう。 Github → GitHub（Hは大文字） Javascript → JavaScript（Sは大文字） After Effect → After Effects（複数形の「s」を忘れてはいけな

テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 本資料をもとにした書籍も発売中です：https://amzn.asia/d/2hQNEk2 Twitter：https://twit…

はじめに 私は、仕事でもプライベートでも分かりやすい文章を書くことを大事にしています。 文章が分かりにくいと、読む人がストレスを感じたり、質問や確認が増えて時間のロスに繋がったりすると思うからです。 『分かりやすい文章を書くために、私が意識していること』というタイトルでLTをしたところ、ありがたいことに好評でした😳 そこで今回、補足も兼ねて記事にしてみました。

大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体