LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた
LINE株式会社は、2023年10月1日にLINEヤフー株式会社になりました。LINEヤフー株式会社の新しいブログはこちらです。 LINEヤフー Tech Blog こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。今日は、私が1文を書くときに気をつけていることや手法についてお話しします。 そして、この書き出しは、6月にmochikoさんが書いた「LINEの社内には「テクニカルライティング」の専門チームがあります」という記事のオマージュになっています。mochikoさんが書いた記事ですごいpvをたたき出したそうなので、人のふんどしで相撲を取ってみようという作戦で始めてみました。 この記事ではLINE社内で私が講師を務めた「LINE社内で大評判のテクニカルライティング講座」に沿って、わかりやすい1文を書くコツを紹介していま
テクニカルライティングの基本を学べます。サイボウズの新入社員向け研修資料です。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 Twitter：https://twitter.com/naoh_nak 2023年度のアップデート版もあります：https://speakerdeck.com/naohiro_nakata/technicalwriting2023
はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと（テクニカルライティングとも言います）は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「テクニカルライティング」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の原理原則を理解して実践を繰り返すことで、必ず一定レベルで習得できるものだと著者は信じています。 もしこのテクニカルライティングの原理原則をまだ体系的に学習したことがない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。 https://developers.google.com/tech-writing Every engineer is also a write
大学や大学院で論文の書き方を鍛え上げた人たちには遠く遠く及ばないが、僕の様なはぐれもの1でも最近は Amazon 社内で文書の質が高いと評価してもらえるまでにはなった。Software Engineer として、コードでのアウトプットはもちろん大事だけど、文書のアウトプット(およびそれによって得られた実際のアウトプット)は同じだけ重要である2。今回は自分が最近どういうところに気をつけて技術文書を書いているのか、ということについて数年後の自分が忘れてないことを確かめられる様にまとめておく。 そもそも文書とは？ 英語だと document。ここで指す(技術)文書とは、人間が読む文体で書かれた技術に関連する情報、といったものだ。具体的に言うと以下の様なものを想定している: 新しいプロジェクトの骨子を説明する資料 会議の叩き台となる 1 枚ペラ 本番環境に変更を加えるにあたっての包括的な情報や具体
テクニカルライティングの基本を学べます。業務マニュアル、報告書、仕様書、技術解説書などのドキュメントを書く機会がある方向け。 サイボウズの2023年度 新入社員向け研修の資料です。 Twitter：https://twitter.com/naoh_nak 2022年版（初版）：https://speakerdeck.com/naohiro_nakata/technicalwriting
こんにちは、Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。先日、このLINE Engineering Blogで「LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた」というタイトルで、1文を書くときに気をつけていることや手法について紹介しました。 前回の記事を簡単にまとめると「たくさんの文案を書いて、一番良さそうなものを選択することがとても大切です」という話を多くの例文を使って説明しました。まだ読んでいない方はぜひ読んでみてください。 今回の記事は、第2弾です。次のステップとして「1文では説明が終わらない文章をどのように組み立てていくとわかりやすいか」という話を、以下のような文章を例に説明していきます。 ここでは、このくらいの情報量の文章を「トピック」と呼びます。 第2弾を最後まで読む
技術をわかりやすく伝えるためのテクニックとしての「テクニカルライティング」を学べます。Developers Summit 2023の登壇資料。開発者・エンジニアの方向け。 https://twitter.com/naoh_nak
システム開発にドキュメントは欠かせません。ドキュメントが得意になれば活躍の幅が大いに広がりますよね。 この記事では、まず冒頭でドキュメントの作成に求められると思うことを整理した上で、そのスキル獲得に役立つと思われる記事や書籍を集めてみました。もちろん他にもあると思うので、もしお薦めのものがあれば是非コメントで教えて下さい 更新履歴 ・2021/04/16：文章術系にリンクを追加しました。 ・2020/11/28：文章術系にリンクを追加しました。 ・2020/07/24：文章術系にリンクを追加しました。 ・2020/05/24：文章術系にリンクを追加しました。 ・2020/05/14：スライドデザイン系にリンクを追加しました。 ・2020/04/29：スライドデザイン系にリンクを追加しました。 ・2020/04/17：文章術系にリンクを追加しました。 ・2020/04/12：関連するTwit
LINEの社内には「テクニカルライティング」の専門チームがあります - LINE ENGINEERING
こんにちは、Developer Contentチームのmochikoです。LINE株式会社でテクニカルライターとして働いています。今日は「テクニカルライター」というお仕事と、LINEにあるテクニカルライティングの専門チームについてお話しします。 テクニカルライターという職種があります テクニカルライターって何をしてるの？何を書くの？ ドキュメントはどうやって書いてるの？ どんなメンバーで仕事をしてるの？ ドキュメントを書く以外にこんなこともしているよ でもドキュメントを書くだけだと技術力が下がらない？ どんな人がテクニカルライターに向いてるの？ テクニカルライターという職種があります 私はもともとウェブ制作会社のインフラエンジニアでした。とある技術書を書いたことをきっかけに「テクニカルライターとして一緒に働きませんか？」と声をかけてもらい、LINEへ転職するに至ったのですが、実はお誘いをい
Send feedback Stay organized with collections Save and categorize content based on your preferences. Every engineer is also a writer. This collection of courses and learning resources aims to improve your technical documentation. Learn how to plan and author technical documents. You can also learn about the role of technical writers at Google.
オペレーション部 江口です。 先日、社内でビジネスライティングについてオンラインで講義する機会があったので、その資料を公開しておきたいと思います。 いわゆる技術文書というよりは、メールやSlackなど、相手とやり取りを行う際の文章作成を主に考えた資料となっていますので、その点ご承知おきください。 背景 講義を行ったのは、アカウント周りの作業を行うアカウントチームに対してでした。チームの業務内でメールでの顧客とのやり取りやSlackでの社内でのコミュニケーションなど、文章を作成する機会が多く、その際の書き方に課題を感じている方が多いようだったので、少しでも助けになればと思いこの講座を企画しました。 私は別に人に自慢できるほど文章がうまいわけではないですが、約20年のエンジニアのキャリアで顧客とのやり取りや技術文書の作成などをそこそこの数こなしてきました。先輩や上司などからいろいろな指摘を貰い
エンジニアのためのドキュメントライティング読みました。 最近の仕事の悩みに対して、方向性を示してくれた良い本でした。 www.amazon.co.jp 自分のチーム内にドキュメントの文化が無い人にお勧めします。 全体のざっくりした感想だと、この手の本にありがちな小言っぽいことは書いてなく、作って意味のあるドキュメントはどうあるべきかを書いてあります。仕事のドキュメントで悩んでいる人には、具体的な取り組みのアイデアがいっぱい見つかるでしょう。 背景 うちの会社は転職者が多く、開発への考え方がバラバラ。当然、ドキュメントに対する考え方もバラバラで必要なドキュメントがなかなか揃わない。今の仕事は各部署からの寄せ集めチームでもあり、ドキュメントのテンプレートみたいなものもない。 世代間の格差も結構ある。ベテラン勢はドキュメントは印刷され保管される前提であり、表示にバージョン、日付、部署、作成者など
読み手を理解してより良いドキュメントを書こう / Write better documents by understanding your audience
ドキュメントを書くときに、みなさんが気をつけていることは何でしょう？ 情報の正確さや文章表現など、さまざまなことに気をつけていると思います。これらに加え、ドキュメントを書く上では、「読み手の理解」が重要です。今回は、2023年3月に発行された『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の内容を元に、どのようにして読み手を理解するか、そしてその重要性を一緒に考えていきたいと思います。 古木 亮太朗 / LINE株式会社 Developer Contentチーム テクニカルライター この資料は以下イベントで発表した内容です。 https://line.connpass.com/event/279668/
こんにちは。Developer Contentチームの矢崎です。LINE株式会社でテクニカルライターとして働いています。LINE社内で大評判のテクニカルライティング講座をブログにまとめてみたシリーズも第3弾になりました。（第1弾、第2弾もぜひ読んでください！） 今回の記事では、以下のようにトピックが多く集まったときに「自分が書いたトピックを（その情報が不要な人に）読ませないためのコツ」を説明します。具体的には、順番に気を配ったり、情報の分類を気をつけたり、タイトルを工夫したり、という話をします。 全部読んでもらおうとしていませんか？ おそらくほとんどの人は、ほかの人の文章を読むときに、必要そうな文だけピックアップして読んだり、タイトルだけで内容を判断したつもりになったりすると思います。検索エンジンで検索したときに、表示された内容だけで、文章の内容を推測して読むか読まないか決めますよね。そう
本コーナーでは技術へのタッチポイントを増やすことを目標に、各分野で活躍されている方をお迎えします。 今回はテクニカルライティングをテーマに堀越さんにインタビューします。書く技術の一端に触れて仕事や趣味に活かしてみませんか。 【話し手】 堀越 良子（HORIKOSHI Yoshiko）LINE ではたらくテクニカルライター。技術書典で『DNS をはじめよう』などのインフラ入門書を執筆。ねこが好き。 Twitter @mochikoAsTech GitHub mochikoAsTech URL https://mochikoastech.booth.pm/ 書く仕事 日高： 今のドキュメントを書くお仕事とは、どのように出会ったのでしょうか。 堀越： 私のキャリアはPHPエンジニアから始まっています。そのあと広報をやって、今の仕事の前はインフラエンジニアを7年ほどしていました。当時、仕事をしなが
Technical Writing One introduction | Google Developers
Send feedback Technical Writing One introduction Stay organized with collections Save and categorize content based on your preferences. Technical Writing One teaches you how to write clearer technical documentation. Target audience You need at least a little writing proficiency in English, but you don't need to be a strong writer to take this course. If you've never taken any technical writing tra
なぜあなたの報告はボスをイライラさせるのか？～その原因と対策まとめ｜藤田肇（Hajime Fujita）
「もっと要点をかいつまんで報告してくれ！」 仕事の報告でボスをイライラさせたことのある人は多いと思います。では、なぜボスはイライラしたのでしょうか？ 「そりゃあ…私の報告が『かいつまんで』いなかったから…」 では、「かいつまんで」いる報告と「かいつまんで」いない報告では、何が違うのでしょうか？ 結論から述べると、かいつまんだ報告は次の３つの条件を満たしています。 （１）前回の報告と今回の報告との関係を説明している （２）結果に直接関係する事実を明らかにしている （３）次のアクションが具体的であるそして、かいつまんだ報告とかいつまんでいない報告との違いは、この条件をきちんと満たしているかいないかなのです。これらの条件を順番に説明しましょう。 １．ボスは前回の報告内容を覚えていない何の前触れもなく、こんな話を誰かに報告されたとします。 「前回の結論を踏まえて、追加でテストマーケティングを行いま
j次のブックマーク
k前のブックマーク
lあとで読む
eコメント一覧を開く
oページを開く
テクニカルライティングの基本
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい - Qiita
質の高い技術文書を書く方法 - As a Futurist...
テクニカルライティングの基本 2023年版
LINE社内テクニカルライティング講座第2弾！1文では説明が終わらない文章を書くコツ
技術をわかりやすく伝えるためテクニカルライティング
ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ - Qiita
Technical Writing | Google for Developers
社内で行ったビジネスライティング講座資料を公開します | DevelopersIO
エンジニアのためのドキュメントライティング - ぱたへね
LINE社内テクニカルライティング講座第3弾！不要な人に社内文書を読ませないコツ
第7回 技術を伝えるドキュメンテーション術 | gihyo.jp