テクニカルライティングの基本 2023年版テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 サイボウズの2023年度 新入社員向け研修の資料です。 Twitter：https://twitter.com/naoh_nak 2022年版（初版）：https://speakerdeck.com/naohiro_nakata/technicalwriting
記事を書くときの自分ルール
この記事は アウトプットはいいぞカレンダー 2022 の 15 日の記事です。 はじめに 記事を書くのは結構好きで、Qiita や Zenn にごそごそと書き続けてたら計 100 記事をとっくに超えてました。今知りました。 「はえ〜そんなにあったのか」って気持ちです。 ちなみに 7 年ほど前の初投稿は、「こういうときはこうすると楽だぞ」ってドヤ顔でコード書いたやつで、数行しか書いてないくせにバグってました。 公開後に即コメント通知が来て、恐る恐る見たら何人かバグ指摘をしてくれてました、懐かしい。 「いんたーねっとこわい、けどやさしい」って思った思い出の記事です。 それから時は経ちある程度は書き慣れて、ここ数年はそれなりに一貫した自分ルールみたいなものができてきています。 気にすることが定まっていると書くとき楽なので、ちょっと整理して晒してみたいと思います。 ネタにしつつあわよくば自分ルール
文章を書くことはプログラミングに似ている。 - CARTA TECH BLOG
技術広報のしゅーぞー(shuzon__)です。 今日は「文章を書くことはプログラミングに似ている」という話をします。 参考書籍はこちら。論理が伝わる世界標準の「書く技術」 @soudai1025からのリクエストで社内ブログを一部編纂し公開しています。 文章を書くことはプログラミングに似ている。 文章を書くことはプログラミングに似ている。 なぜならば、抽象化すると、一連のトピックに対する意味のあつまりを区切り、扱う行為だからだ。 意味ごとに構造化する行為と思えば非常に似ている。 パラグラフ・ライティングは関数に似ている ここでパラグラフ・ライティング を紹介しよう。 パラグラフの構造 パラグラフ・ライティングは関数に似ている。 パラグラフ・ライティングは段落の先頭に「その段落が持つトピックの結論」を書く。 その後、前述の事実を用いた補足とロジックが続きトピックを補足する。 段落の最後に、議論
読みやすいドキュメントを書くために今日からできる7つのこと｜壮｜Masato Tanaka
こんにちは。壮（@sew_sou19）と申します。 メガベンチャー企業でエンジニアとして働いています。 エンジニアにジョブチェンジした当初は、ドキュメントの書き方なんてこれっぽっちも分かりませんでした。読みやすいドキュメントを書くことが本当に苦痛だったのですが、考えて、試行錯誤し続けた結果、以下のような評価を得るに至りました。 リーダーから「君は情報の整理が上手でドキュメントが本当に読みやすい。チーム全体の能力向上に繋げたいからドキュメント書く際のポイント共有してほしい」と言われたので、意識していることを言語化しつつテクニカルライティングの本でインプットしてるけど、学びが多い。ついでにnoteにもまとめてる — 壮 (@sew_sou19) November 28, 2022 そこでこのnoteでは、僕がドキュメントを作成するときに、特に意識して実践している7つのことを書きます。（本当は2
果てしない文章推敲を「３ステップ」で効率的に終わらせる方法｜石原尚（大阪大学教員）｜note
文章は、「これで伝わるだろう」という淡い期待を簡単に裏切ります。伝えたいことを期待通りに伝えられるようになりたいのなら、「表現の質」を高めるための推敲の技術の習得が不可欠です。 この記事では、大切ながら手間のかかる推敲を「効率的に」実施する方法を紹介します。ほとんどはじめて論文を書くことになった学生さんが、論文原稿（卒論・修論）の価値を飛躍的に向上させるうえで役にたちます。また、論文に限らず、「正しく、詳しく、丁寧に伝えたい」という気持ちで文章を書こうとする場合には、さまざまな場面で使えるはずです。 この記事で紹介する推敲の手段は、「切り分ける・並び替える・繋ぎ方を変える・削り落とす・一貫させる・まとめる・明確にする・限定する・やさしくする」の９種類です。この９種類さえ自由自在に駆使できれば、論文の文章を劇的に良くすることができます。この９種の推敲を、「まず工事して、片付けて、最後に気遣い
プログラマーに贈る、わかりやすい文章を書くための技法 - LIVESENSE ENGINEER BLOG
これは Livesense Advent Calendar 2022 DAY 8 の記事です。 転職ドラフトでエンジニアをしている verdy_266 です。 僕の2022年を振り返ると、採用広報チームでの活動を無視することはできません。転職ドラフトの開発を行う傍ら、昨年末に採用広報チームにジョインし、記事の執筆や校正に多くの時間を割いてきました。 今まで記事を投稿したことがなかったこちらのブログにも共作含め5記事を投稿し、11月には Software Design への寄稿の機会をいただくこともできました。文章を書くことが思った以上に好きなんだなと発見があった年でもありました。 made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp made.livesense.co.jp 弊
伝わる文章 | 基本要素 | SmartHR Design System
相手に誠実に、わかりやすい文章を書くための心がけをまとめました。 どういう思考プロセスからどんな表現が生まれるのか、参考として実例を紹介しています。実際に読み比べ、SmartHRの従業員として何かを伝えようとするときの、参考にしてください。 伝わる文章のガイドライン何を伝えるかによって、必要な情報の量や説明の粒度は異なります。 情報が不足していたり、逆に情報が多すぎたりすると、読者が意図を読み取れないことがあります。 読み手となる相手の状況（読む場面、事前知識など）を踏まえ、言葉にする内容や表現を厳選することが大切です。 目的に合わせて情報を取捨選択する読者の目線に立ち、コンテンツの目的に合わせて情報を取捨選択しましょう。 実例1：法律や業務に関わる記事目的業務に関係する「厚生年金保険」について正確に知りたいと思っている人に、わかりやすく内容を伝える。 Before日本の年金制度は、全国民
らいおんの隠れ家 : ポール・グレアム「文章術・簡易版」 - livedoor Blog（ブログ）
ポール・グレアムの「文章術・簡易版」(Writing, Briefly)を翻訳しました。原文はココです。 なお翻訳にあたり、practicalscheme様、kokezaru753様のコメントを反映させています。 http://q.hatena.ne.jp/1142919962 文章術・簡易版 2005年3月 (多くの人が、文章術に関するアドバイスを求めている。その1つに答えていたら、たまたまそのテーマに関する短いエッセイになってしまった。私はふつう、1つのエッセイに数週間をかける。このエッセイには67分かかった -- 執筆に23分、推敲に44分だ。私は実験として、このエッセイをオンラインにアップしよう。少なくとも内容はとても濃い) 私は、たいていの人が考えているよりも、上手に書くことはずっと重要だと思う。文章を書くことは考えを単に伝達するだけじゃない。考えを生み出すんだ。文章を書くのが下
『理科系の作文技術』を久しぶりに読み返し、とにかく「6 はっきり言い切る姿勢」「7 事実と意見」だけは絶対にみんな読んだ方がよい、と思った - Magnolia Tech
理科系の作文技術（リフロー版） (中公新書) 作者:木下是雄発売日: 2016/10/14メディア: Kindle版 いまさら紹介するまでもないけど、とりあえず作文方法を学びたい時は、まずはこの「理科系の作文技術」を読むことをお勧めする。 最近ブログのエントリをざっと書いてそのまま公開してしまうことが多かったので、少し反省し、それを直すためにこの本を改めて読み直した。そうしたら、タイトルで全部言い切っているのだけど、とにかく「6 はっきり言い切る姿勢」「7 事実と意見」だけは絶対にみんな読んだ方がよい、と思った。 日常的にメールや、ブログの記事など、それなりの量の文章を書くことが多いけど、論文や雑誌の記事など、きちんと他人の目を通した上で公開される文章を書くことは、まずない。一度だけ、雑誌の記事原稿を書いたとき、自分なりにかなりの推敲を重ねたつもりでも、プロの編集の方から見れば言葉使いや、
モノや概念をわかりやすく伝えるテクニック
録画：https://www.youtube.com/watch?v=49CzhFGqvD8 概要： 何かの技術、商品、サービスや機能など、モノや概念を人に説明しなければならない場面は多くあります。 伝えなくてはならないことはいっぱいあるけれど、何からどんな順番で伝えたらいいのかわからず、時間だけが過ぎて焦ってしまう、そんな経験はありませんか？ テクニカルライターが情報をどう整理して構造化しているかをお伝えします。
開発ドキュメントの書き方！9つのコツ【エンジニア】
文章を書く前にやることよい文章を書くには、実際に文章を書く前に、読者は誰か、どういう悩みを解決するのかを企画することが大切です。また、それを元にアウトラインを書いておきます。 このふたつを元に文章を書くことで、読みやすい開発ドキュメントにつながります。これについては、次の記事をご覧ください。 開発ドキュメントを書く前に決めるべき3つのこと【企画編】開発ドキュメントにおけるアウトラインの書き方開発ドキュメントの書き方企画とアウトラインの作成が終わったら、実際に文章を書いていきます。文章を書くときは、次の9つを意識して書きます。これだけで、読みやすさ、分かりやすさが大きく向上します。 一文を短く切る結論を先に述べる指示語を使わない主語を明確にする、述語との距離を近づけるひらく・閉じるを統一する再現条件を示す前提を揃える見出しや箇条書き、表などを適切に用いる読者に伝わる用語を使うひとつずつ説明し
スケベ小説を書くときの参考書・ツールまとめ
喚く狂人 @wamekukyouzin コミケで「スケベ小説を書くにあたって使っている参考書」みたいな話をしてたら、「それTwitterに書いてまとめたら？」という話になったので、色々紹介していきます。 2022-01-01 23:31:21 喚く狂人 @wamekukyouzin 文が読みづらいと「使いづらい」ので、なるべく分かりやすくしたいです。そこで本田勝一「日本語の作文技術」。 修飾語の順序であったり句読点の使い方について体系だって解説するベストセラーです。エロに限らず趣味で小説を書くなら是非読むとよいと思います。 ただし例文の政治的思想が強いです。 2022-01-01 23:31:42
伝えたい人に届ける技術記事の書き方 - Qiita
こんにちは、リファクタリングが大好きなミノ駆動です。 この記事は READYFORアドベントカレンダー2021 、初日の記事です。 なにこれ？ 苦労して執筆した技術記事は、伝えたい人にしっかり伝えたいですよね。 また、最後まで読んでもらいたいですよね。 一方で、構成などに課題があって、伝えたい人になかなか伝わらないことがあります。 この記事は、伝わる記事の書き方について、私の個人的なノウハウを書き記したものです。 これからアドベントカレンダーの記事を執筆される皆さんにとって、少しでもお役に立てられれば幸いです。 この記事のゴール 以下の理解を得ることをゴールとします。 以下2つの要件を踏まえた記事構成を心がけること。 構成要件①：技術を紹介する上で最低限説明の必要な内容を網羅すること。 特に課題をしっかり伝えること。 構成要件②：読み手が段階的に理解しやすい順番になっていること。 告知の仕
伝わる文章作成の基本を学ぶための記事・学習コンテンツのまとめ - Qiita
短いメッセージを書くことはできても、まとまった文章を書くのに苦労している人は多いのではないでしょうか。 この記事では、まとまった文章を作るときの技術を学ぶことができる記事や学習コンテンツを紹介します。新人エンジニア向けです。 文章の「型」を学ぶ まとまった文章を書くには、「型」が必要です。頻繁に使うものは、「型」を覚えてしまいしましょう。 バグレポートの書き方を学ぶ エンジニアとして書く文章の代表例が、バグレポートです。 バグレポートでありがちな失敗として「何が問題だと思っているのか」が伝わらないというものがあります。 これを防ぐために、「期待する結果」「実際の結果」「再現手順」の3つを必ず書くようにしましょう。 質問の書き方を学ぶ エンジニアが扱う技術は、最初はわからないことだらけです。 それを解決するために、質問の文章を作成する技術が必要となります。 概ね下記の4つの情報があれば、良い
読んでもらえる文章にするための「パワーワード」の作り方｜竹村俊助／編集者
今日はぼくの企業秘密的な話をします。 ぼくの文章はたまに「わかりやすいです」とか「気づけば最後まで読んじゃいました」などと言ってもらえるのですが、自己分析では、そこまで文章がうまいとは思っていません。 じゃあ何が違うのかというと、「パワーワード」というものを巧みに使えているからなんじゃないかと思っています。タイトルはもちろん、見出しや文章の随所に「パワーワード」を入れることで、読み手を惹きつけることができているのではないか。 パワーワードという言葉はどうやら「意味がわからないけど強い言葉」という意味で使われていたこともあるそうですが、ここでは単に「人を惹きつける力のある言葉」という意味で使います。 パワーワードは「香辛料」パワーワードは香辛料に似ています。 チーズとソースだけのプレーンなピザは、ずっと食べていると飽きてしまいます。でも途中でタバスコをかけると飽きずに食べられますよね？ 素う
日本語エラーチェックサイトenno.jpを作った理由｜TechRacho by BPS株式会社
こんにちは、hachi8833です。はっと気がつくと、私が運営している日本語エラーチェックサイト「enno.jp」を開始してからもう8年が経過していましたので、たまには振り返ってみたいと思います。 サイト: 日本語の文章のタイポ/変換ミス/誤字脱字エラーをチェック/校正 | enno.jp enno.jpより 使い方はあきれるほど単純です。チェックしたい文章をフィールドに貼り付けてボタンを押すだけ。 enno.jpは、自分で作って自分で使い、自分で常にパターンを追加/更新しています。いわゆるドッグフーディングというヤツです。当然この記事もenno.jpでチェック・修正しました。 参考: ドッグフーディングとは:意味/解説 - シマウマ用語集 今年1月に突然enno.jpがバズッて自分でもびっくりしました。広めていただきありがとうございます🙇。 「外出自粛要請」が文章校正に引っかかってワロ
正確な文章の書き方
このページでは、正確な文章を書くための秘訣をまとめてみようと思います。それほど文章がうまいとはいえない私が、文章の書き方について述べるのですから、むこうみずな行為であることは百も承知です。しかし、数年に渡って探求した正確な文章の書き方が、少しでもみなさんの役に立てばという思いを自分への励ましに代えて筆をとります。 ここでお話するのは、「文章をいかに正確に書くか」や「自分の考えをどうやったら適切に表現できるか」であって、決して「どうやったら人を感動させる名文句が書けるのか」ではありません。 このページを読んだら「科学技術文献」を書くための技術が少しは身に付くのではないかと期待しています。しかし、 人はいさ 心も知らず ふるさとは 花ぞ昔の 香ににほひける (紀貫之) などのような心に残る文章が頭に浮かぶようになるわけではありません。 絵の書き方に例えて言うなら、ここで述べる内容は、色彩や調和
LINE社内テクニカルライティング講座第3弾！不要な人に社内文書を読ませないコツ
こんにちは。Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。LINE社内で大評判のテクニカルライティング講座をブログにまとめてみたシリーズも第3弾になりました。（第1弾、第2弾もぜひ読んでください！） 今回の記事では、以下のようにトピックが多く集まったときに「自分が書いたトピックを（その情報が不要な人に）読ませないためのコツ」を説明します。具体的には、順番に気を配ったり、情報の分類を気をつけたり、タイトルを工夫したり、という話をします。 全部読んでもらおうとしていませんか？ おそらくほとんどの人は、ほかの人の文章を読むときに、必要そうな文だけピックアップして読んだり、タイトルだけで内容を判断したつもりになったりすると思います。検索エンジンで検索したときに、表示された内容だけで、文章の内容を推測して読むか読まないか決めますよね。そう
読み手をイライラさせない技術記事などを書くために最低限守ったほうがいいこと - Qiita
追記: この記事は「人が一生懸命書いた記事を読んでイライラする人間」を擁護するつもりは一切ありません。 追記: この記事は「自分の記事ではイライラさせたくないな」と思う人向けに執筆したのであって、この記事のあることをQiitaにあるすべての記事に矯正したいという思想のもとで執筆したものでは有りません。 はじめに こんにちは Qiitaやnoteといった情報共有に向いたサービスがどんどん普及しており、知識量に関係なく誰でも情報が発信できるいい時代になりましたね。 しかし、投稿されているすべての記事が良いと思えるわけではないのは確かです。タイトルに書いてあるものとは違う内容が書いてあったり、問題解決まで達していない結論で終わってたり。記事中の動かないコードを調べるために、そこから別の記事をはしごをして、それを繰り返していた結果業務時間が終わっていたり。 あまり私も人のことは言えませんが、いろん
リリース、障害情報などのサービスのお知らせ
最新の人気エントリーの配信
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本
