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

テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://spe…

中村明博（編集者） @naka727 【編集者からのお願い】 著者やライターさんへ、原稿が完成したら、 ・「という」をカット ・「と思います」をカット ・「こと」をカット ・「もの」をカット ・過剰敬語をカット できないか見直していただけないでしょうか。ざっとでもかまいません。関係者全員が幸せになります。なにとぞ、、！ 中村明博（編集者） @naka727 【なぜこんなお願いをするか】 誰かが直さなければならないからです。その分、「磨き上げ」の時間が減り、本のクオリティーが落ちます。本の売り上げが落ち、関係者全員が不幸になるためです。 中村明博（編集者） @naka727 さらに可能なら、 ・40字を超える長文は短く・簡潔にする ・「これから説明します」的な余計な前置きはカット ・「ひとつ・1つ」「ひとり・1人」あたりの表記統一を行う このあたりまで見ていただけると、編集者はみな泣いて喜び

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

はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと（テクニカルライティングとも言います）は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「テクニカルライティング」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。 もしこのテクニカルライティングの原理原則をまだ体系的に学習したことがない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。 https://developers.google.com/tech-writing Every engineer is also a write

You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session. You switched accounts on another tab or window. Reload to refresh your session. Dismiss alert

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

技術書典４に申し込んだけれどもまだキャンセル可能だという時期に、 自分の中の ・自分みたいな素人が技術書書いたってバカにされるだけだという勢力と、 ・技術書典で販売側に立ちたい&もし良いものができなくても今後成長すればいいでしょうって勢力 が闘っていた時に、背中を押してくれた結城先生のツイートを貼ってみます。 もしかしたら、これが次の誰かの脊中を押すかもしれないですしね！ 結城先生のツイート そして思います。文章は、そのつど書かなきゃ駄目ということを。経験を積んでから、十分学んでから、時間ができてから書くのではない。断じて違う。そのつど書く。自分の不十分さをたっぷり自覚した状態で書く。そうでなければ、いつまでたっても書けやしない。— 結城浩 (@hyuki) 2017年11月16日 あなたに強制するわけではなくて、結城の独り言です。十分準備ができて、世の中に出しても恥ずかしくない状態になっ

はじめに こんにちは植木和樹＠上越妙高オフィスです。クラスメソッドではAWSを始め、弊社で取り扱っている製品・サービスに関するサポート業務を行っています。 サポートでは日々様々なお問い合わせを受け付けるわけですが、ご質問に対する回答内容は正しくても、言葉が足りないためにお客様が不満に感じてしまうことがあったりします。「正しいことを伝えたのに、どうして不満と感じたんだろう？なにが足りなかったんだろう？」と対応を振り返る際に、私はキーワード／パターン／フレームワークに当てはめてみて考えるようにしています。 今回はサポートメンバーがよりよいサービスが提供できるよう、自分のアンチョコから5つのキーワードをご紹介したいと思います。 1.安心してもらう 自分で書いた回答内容を見返してみましょう。文章の内容がお客様に安心を与えているでしょうか？ 最後に「安心です」がつくように意識しましょう。また「文章の

※最終更新日2017年6月14日 これをするだけで格段に文章力がアップする 今日ブログをいろいろ見て思ったこと。 改行のはなし - はてな編集部ブログ「編む庭」 文法的には間違ってないのに違和感がある日本語とは - 脳内会議 はてな編集部さんのブログでビビッと来たのはここ。 つまり、インターネットにおいて人にどう読まれるかを意識するのであれば、形式改行を積極的に利用するにせよ、排除するにせよ、その表示に対してより自覚的にならざるを得ず、レイアウトまでも含めた文章の「空間を編集する」ことが、現代のWeb編集者には求められているのです。 改行のはなし - はてな編集部ブログ「編む庭」 改行というのは文章を見やすくするための「空間を編集すること」だというんですね。なるほど奥が深い。確かにみっちり埋まっているような文章は言葉を拾いにくいし、適度に隙間のある文章のほうが分かりやすいしなんといっても白

ネットの編集・ライティング界隈に人知れず一匹の妖怪が棲み着いている。それこそが「改段落なき改行」。すなわち文章の途中であっても任意の句読点で（あるいは句読点すらなくても）行を改める表記のことである。 これはほんとうに些細で日常的な、なんのこともなく見過ごされがちな文章の書き方であるとともに、見過ごしたにしても何らかしらの問題に発展するともおもえない、平たくいうならひとつのbr要素にすぎないのだが、正面から向き合おうとするとなかなかにやっかいな側面を持っているのである、という持って回ったような大仰な話をこれからしようとおもいます。 こんにちは。はてな編集部のid:mohritarohです。最近はセブン-イレブンの「黒糖まん」がお気に入りで、駅前のコンビニに立ち寄るたびについ買ってしまいます。という書き出しを用意していましたが、本稿の執筆から公開までの間にメニューから消えてしまいました……。

社内向けの教育資料を、ど素人でもわかるようにと思いながら作っていて、じゃあ「わかりやすい」って何だろうって考えてた。今まで読んできたいろんなわかりやすかった本とそうでない本を思い浮かべながら、一般的にここを注意すればわかりやすさを確保できるだろうっていうポイントを一旦まとめておこうと思った。そうしてまとめてみると、本に限らず人に何かを伝えること一般に適用される話だなと思った。 読む側の負担を減らす わからない＝理解をはばむ障害物がある。この障害物を取り除く／回避する作業が「わかる」ために必要になる。その作業を、作者ではなく読者が負担するとき「わかりにくい」本になる。 日本社会だと情報の受け手の側がこの「わかる」ための作業を負うことでコミュニケーションを成立させる傾向にある。空気を読むというようなことだ。そのため発信者側が事前に手を尽くしてわかりやすく発信するというのが苦手で、相手が汲み取っ

いくつかのオープンソースプロジェクトを公開している筆者からの、読みやすくユーザーにやさしいREADMEを書くためのアドバイス。 この記事は、Rowan Manning氏による「Writing a Friendly README」(2016/3/14)を翻訳したものです。 あなたのプロジェクトのREADMEは、かなり重要です。そこはプロジェクトに初めて来た人が大抵最初に見るであろう場所であり、唯一のドキュメントであることもよくあります。あなたのオープンソースプロジェクトにとってのREADMEは、企業にとってのウェブサイトのようなものです。ウェブサイトはユーザーエクスペリエンスの注目を集めるところですが、READMEがユーザー観点で考えられることはほとんどありません。 この記事では、分かりやすいREADMEを書くために役立ち、開発者(ユーザー)の要求に見合い、開発者がプロジェクトを初めて見たの

野口悠紀雄『話すだけで書ける究極の文章法 人工知能が助けてくれる！』(講談社)に驚いたことを伝えようと、この文章を書いているのだが、その前にちょっと聞いてほしい。 革命が起きたと大騒ぎになった。 ライターコミュニティでの話だ。 インタビュー記事を作るのはたいへんだ。 いろいろ苦労はあるが、そのうちのひとつは音声起こし。 インタビューで喋ったことをいったんすべて文字にする。 話者のニュアンスを再確認し、どう構成するかの基盤となる。 もちろんインタビュー原稿の作り方はひとそれぞれだが、音声起こしを丁寧にやる人は、完成原稿も丁寧だ。 だが、これが本当に面倒だ。 １時間の音声を起こすには、慣れてる人でも３時間ぐらい。慣れてなければ５時間ぐらいかかってしまう。 タイピングが速くても、喋りには追いつかない。 変換もある。誤変換もある。聞き取りにくい部分もある。 喋りは止まらないので、追いつかなくなると

ituore.com 2024 著作権. 不許複製 プライバシーポリシー

最近はブログを始めマニュアルや仕様書など技術文書を書く機会が多くなってきました。 技術文書はわかりやすさが重要だと思うのですが実際は書けていません。 どうしたらわかりやすい文書が書けるのだろうか？と調べていたら RedPen というツールを見つけたので早速試してみました。 RedPen とは？ RedPen とはプログラマや記者が規約に従って文書を記述するのをサポートしてくれるオープンソースのソフトウェアツールです。 プログラミングが規約に従ってコーディングされているかチェックするように、RedPen は自然言語で記述された入力文書の検査を自動化してくれます。 RedPen の特徴 設定が柔軟に行えます。（カスタマイズも柔軟） どのような言語で書かれた文書でも処理できます。（もちろん日本語も OK です） Markdown や Textile フォーマットで記述された文書をそのまま検査でき

以前、プラグインで拡張可能な文章校正ツール textlint で小説の作法を検証するための規則を作ったのですが、textlint はコマンドラインツールであるために利用するまでのハードルが高い状況でした。 Sublime Text や Atom などのプログラマ向けエディタを利用していれば、textlint のプラグインが使えたりするのですが、今回はより簡単に利用できるように Chrome の拡張機能として textlint をブラウザ上で使えるようにしてみました。 インストールはこちら: 【Chrome ウェブストア】 textlint: 文章チェッカー インストールすると、ページ内の編集領域で文章入力中にリアルタイムで校正してくれるようになります。（もちろん ON/OFF できます） textlint に最近追加された自動修正機能にも対応しているので、ボタン一発で自動で修正されたりしま