2024.10.01
自社の社内情報を未来の“ゴミ”にしないための備え 「情報量が多すぎる」時代がもたらす課題とは?
リンクをコピー
記事をブックマーク
岩瀬義昌氏:ご紹介いただきました、岩瀬と申します。よろしくお願いします。『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』は、もともと『Docs for Developers: An Engineer’s Field Guide to Technical Writing』という洋書だったんですが、その翻訳をして、今回この機会をいただいています。
余談ですが、APC(株式会社エーピーコミュニケーションズ)さんが「カプセルトイ」を作られていたんですね。めちゃくちゃ評判が良くて、「めちゃくちゃほしかったです」ということだけ言ってから始めたいと思います(笑)。
さっそく中身にいきましょう。今日は「30分でわかる『エンジニアのためのドキュメントライティング』」ということでペルソナを少しおさらいしておくと、今回のトークはこんな人向けになっています。(スライドを示して)エンジニアであれば「あー、ドキュメントを書いておけば良かったなぁ」となった経験が、おそらく1回や2回はあるんじゃないかなと僕は思っています。正直僕はけっこうあります。
ただ一方で矛盾があって、「そういえば、ドキュメントの書き方って体系的に網羅的に学んだことがないよね」みたいな方もけっこう多いと思っています。もちろん社内などの研修はあるかもしれないですね。
今回はそういうものを学んだことない方向けの本になっています。イベントの残り30分程度で話をしますが、一部、特に私が重要だと思った部分を紹介していきます。時間があればプラスαのところも少しおさらいさせてもらえればいいかなと思っています。
(スライドを示して)今日はこの対象者に向けて、「30分後にドキュメントライティングのスキルがちょっとでも高まっていればいいかな」ということをゴール地点として狙っています。
この(ドキュメントライティング)スキルって何かというと、例えば「ドキュメントライティングってこうやって書いたらいいんだ」という概要を知っているとか、ドキュメントって準備・作成・運用で、作る前に何かしら仕込んで実際に書いてみて、リリースしてみてという普通のフェーズがあるので、ここで何に気をつければいいのかという重要なポイントを理解することを狙っていきたいと思います。
今回は洋書なので、日本語特有の観点がぜんぜんないんですよね。先ほど言ったプラスαは、時間が余ったら私的に推したい部分があるので、紹介していきます。
私の自己紹介をぜんぜんしなかったので一瞬だけ自己紹介すると、名前は岩瀬義昌と言います。Twitter(現X)は@iwashi86でやっているので、よければフォローしてもらえるとありがたいです。
本業は通信企業でプロダクトマネジメントやアジャイル開発をしていて。また(それとは別に)組織支援とかもいろいろやっています。サイドワークも本当にいろいろやっていて、その中の1つで翻訳者として洋書籍を翻訳しています。
(スライドを示して)一番下に書いてある「ポッドキャスター」は、私の(やっていることの)中ではたぶん一番よく知られているものだと思っていて、fukabori.fmというテックポッドキャストをやっています。実際にこの本の著者にも出てもらっているので、英語なんですが、もし興味があれば聞いてもらえるとおもしろいエピソードがあります。書籍には実はコーギーの犬が出てくるんですけど、「それはもともと『カウボーイビバップ』から来た」みたいな裏話も(fukabori.fmの中に)あるので、興味があればどうぞ。
ということで本題に入っていきましょう。今日の本題は、先ほど言ったとおり、ドキュメントの概要をしゃべっていきます。(スライドを示して)上からざっといくと、書籍の概要をしゃべった上で、特に翻訳者視点から「ここは意識してほしいな」というところを4章ほど紹介します。最後に時間があればプラスα。さっそく上からいきたいと思います。
書籍の概要です。ではさっそくいきましょう。書籍を書くにあたって、概要はパート1、パート2、パート3の3つに分かれています。パート1はドキュメント作成の準備というところで、実際に読み手は誰なのか、どうやって作ったらいいのかと計画していく部分が最初のところです。
2つ目のところが実際に書いていくドキュメント作成の部分で、これが3章から6章になっています。ドラフトは下書きみたいな感じですね。3章は下書きを書いて、下書きをさらに編集して精度を上げていって、必要であればサンプルコードを入れて、あとは図表とかを入れるみたいな流れになっています。
最後のパート3は何を書いてあるかというと、書いたらリリースで出すじゃないですか。ドキュメントはリリースしても終わらないんですよ。プロダクトと一緒ですね。リリースはむしろスタート地点で、公開したらフィードバックをもらって、その品質を測定してより良くするにはどうしたらいいのかということを考えます。
それでさらにものが増えてくると、ドキュメントがたくさん増えて探すのが大変になるので、構成全体のリファクタリングをしないといけないとか……。それ(書いてあるの)が10章ですね。
最後の11章が、ドキュメント保守と非推奨化です。これはデプリケート(deprecate)です。ドキュメントも最後はなくなるので、最後のなくなるプロセスまでが書かれているのがこの章になっています。
今日はこのうちの1、3、8、9章を特にちゃんとしゃべります。
ここ(の4つの章)に注力するので、他のポイントは先ほどしゃべったとおりで、基本的にはサラッとしか書いていません。資料はハッシュタグで放流しようと思うので、もし興味があれば、読んでもらえれば全体の概要の概要ぐらいはわかるかなと思います。
作成の部分も先ほどと同じく言ったとおりで、ドラフトを書いて精度を上げるプロセスです。
最後のパート3に関しては、何かを出してリリースして改善していくところになっています。
ここで言いたいのは別のことで、これはプロダクト開発とまったく同じことをやります。ドキュメントに関しても、プロダクトの1つなんですよね。プロダクトを作る時には、最初にユーザー理解をするじゃないですか。「どんな課題を解きたいのか」を理解していく。どういうユーザージャーニーをたどっていくのかを計画していきますよね。
そしたら、(出来上がった計画は)あくまで仮説でしかないので、仮説検証しにかかるんですよ。そのために我々は実際にプロダクトを開発する。ソースコードを書いてレビューをして、プロダクトを作っていく。それができたら外に出して、リリースして、反応を見る。(そうすると)ユーザーから必ずフィードバックが何らかある。「ない」というのもフィードバックの一種ですね。ユーザーからのフィードバックがないのも別の問題があるはずです。
さらに使われていない機能をプロダクトから消す。ソースコードから消すと気持ちいいですよね。重要ですが(これは)ドキュメントも一緒で、不要な機能を減らしていくのはとても大事なので、それもやっていきます。
そうするとまたユーザーの理解が進むわけなので、またユーザー理解に戻って、「こんなことを書いていけばいいんじゃないか」ということを計画していくということをグルグル回すのがプロダクト開発の流れになっています。
「ドキュメントでもまったく同じことを扱いますよね」ということが書かれているのがこの本です。全体像が書かれていて超細かいところは書いていないんですが、少なくとも最初から最後まで(の全体)を知れる本だと思ってもらえればいいかなと思います。
(スライドを示して)さっそく中に入っていきますが、1点だけ注意点があるのでちょっとだけおさらいさせてください。何かというと、この本はエンジニアが作る・使うドキュメントに集中している書籍です。だから「どうやってパラグラフを構成させればいいですか」みたいな、ドキュメントのロジカルライティングやパラグラフライティングと言われたりするものに関しては、まったく触れられていないです。
(そのあたりのことは)もう知っていることが当たり前な本になっているので、(その前提部分のことに)もし興味があれば、私が良いなと思っている本を3冊ほど右下に書いておいたので、合わせて読んでもらえると、文章力は非常に上がるかなと思います。
『理科系の作文技術』とか『ロジカル・ライティング』、また『考える技術・書く技術』とかの新版など、いろいろなものも出ているので、見てもらうといいかなと思います。ご参考までにどうぞ。
(次回につづく)
関連タグ:
2024.10.29
5〜10万円の低単価案件の受注をやめたら労働生産性が劇的に向上 相見積もり案件には提案書を出さないことで見えた“意外な効果”
2024.10.24
パワポ資料の「手戻り」が多すぎる問題の解消法 資料作成のプロが語る、修正の無限ループから抜け出す4つのコツ
2024.10.28
スキル重視の採用を続けた結果、早期離職が増え社員が1人に… 下半期の退職者ゼロを達成した「関係の質」向上の取り組み
2024.10.22
気づかぬうちに評価を下げる「ダメな口癖」3選 デキる人はやっている、上司の指摘に対する上手な返し方
2024.10.24
リスクを取らない人が多い日本は、むしろ稼ぐチャンス? 日本のGDP4位転落の今、個人に必要なマインドとは
2024.10.23
「初任給40万円時代」が、比較的早いうちにやってくる? これから淘汰される会社・生き残る会社の分かれ目
2024.10.23
「どうしてもあなたから買いたい」と言われる営業になるには 『無敗営業』著者が教える、納得感を高める商談の進め方
2024.10.28
“力を抜くこと”がリーダーにとって重要な理由 「人間の達人」タモリさんから学んだ自然体の大切さ
2024.10.29
「テスラの何がすごいのか」がわからない学生たち 起業率2年連続日本一の大学で「Appleのフレームワーク」を教えるわけ
2024.10.30
職場にいる「困った部下」への対処法 上司・部下間で生まれる“常識のズレ”を解消するには
2024.10.29
5〜10万円の低単価案件の受注をやめたら労働生産性が劇的に向上 相見積もり案件には提案書を出さないことで見えた“意外な効果”
2024.10.24
パワポ資料の「手戻り」が多すぎる問題の解消法 資料作成のプロが語る、修正の無限ループから抜け出す4つのコツ
2024.10.28
スキル重視の採用を続けた結果、早期離職が増え社員が1人に… 下半期の退職者ゼロを達成した「関係の質」向上の取り組み
2024.10.22
気づかぬうちに評価を下げる「ダメな口癖」3選 デキる人はやっている、上司の指摘に対する上手な返し方
2024.10.24
リスクを取らない人が多い日本は、むしろ稼ぐチャンス? 日本のGDP4位転落の今、個人に必要なマインドとは
2024.10.23
「初任給40万円時代」が、比較的早いうちにやってくる? これから淘汰される会社・生き残る会社の分かれ目
2024.10.23
「どうしてもあなたから買いたい」と言われる営業になるには 『無敗営業』著者が教える、納得感を高める商談の進め方
2024.10.28
“力を抜くこと”がリーダーにとって重要な理由 「人間の達人」タモリさんから学んだ自然体の大切さ
2024.10.29
「テスラの何がすごいのか」がわからない学生たち 起業率2年連続日本一の大学で「Appleのフレームワーク」を教えるわけ
2024.10.30
職場にいる「困った部下」への対処法 上司・部下間で生まれる“常識のズレ”を解消するには