テクニカルライティングチームの仕事についてまとめる。テクニカルライティングチームを作りたい開発チームを想定し、「テクニカルライティングチーム」の役割を概観する。2021年10月頃更新。
Hint
分かりやすいドキュメント、書けていますか?
Amazon、Google、Facebook、Evernote、GitHub…多数の企業が実践しているマーケティング手法がDevRel(Developer Relations)です。外部の開発者とのつながりを形成し、製品やサービスを知ってもらうこと、さらに彼らの声を聞くことでサービスの改善や機能追加に活かしていく活動になります。日本でもエバンジェリストやデベロッパーアドボケイトと呼ばれる方が増えており、製品やサービスを紹介しています。DevRel Meetup ではそうしたエバンジェリスト、DevRel活動を行っている方が集まり、知見を共有したり情報交換をする場にしたいと考えています。イベントを繰り返すことでDevRelやエバンジェリスト、アドボケイトの認知度向上をはかりたいと考えています。
今回のテーマはライティングです。Content is kingとは昔からよく言われます。分かりやすいドキュメント、読みやすいコンテンツはそれだけで開発者からの信頼を得られるでしょう。そんな書き方の基本を学び、話し合いましょう!
対象者
DevRel活動(開発者向けPR)に興味がある人
マーケティングに携わってる人、興味がある人
エバンジェリスト・デベロッパーアドボケイト
エバンジェリスト・デベロッパーアドボケイト活動に興味がある人
開発文書部が解決する課題
開発による文書作成が属人的である
- 量や巧拙がまちまちである。
- 用語の用法がまちまちである。
- 用語の理解がまちまちである。
- 技術文書を書く基本知識がない。
- 文書整頓されていない。
- 退職した人の資料が見つからない。
- 体系立てて書けていない。
開発者が専門ライティングまで担うには重荷である
- プログラム開発工数がライティングに消費されてしまう。
- 決まりきった文書にはテンプレートがほしい。
- 「です、ます」体や時制の統一など、ガイドに則った細かい校正は開発者が担う必要はない。
- より多くの人に読んでもらうことを想定した文書に専門家が必要である。
- 役割分担が必要である。
社内文書が常に陳腐化してしまう
- 社内Wikiの情報管理、共有ファイルドライバ等の情報管理。
- 履歴管理、変更理由の管理。
- 決定記録の管理。
- 新人が加わった時に自力解決ができない。人に聞くことをやっていると時間的制約が生まれる。
- なぜそういうルールが有るのか分かりづらい。探すとここにあるとか言われるが知らないと見つけられない。
- 知識をためても活用されない。事故再発防止策を溜めても工夫しないと再利用が難しい。
- なぜ当時そういった意思決定に至ったのかの記録が残らない。
- サードパーティ製ライブラリ、アーキテクチャの決定記録などが残らない。
- 結局口頭伝承になってしまう。
- 情報を会社の財産と考えてきちんと管理する意識づけ。
公開する文書を洗練させたい、あらゆる開発者に有効に発信したい
- 社内コミュニティから社外コミュニティへの橋渡し、自主的活動の後押し
- 非エンジニアにも伝わる言葉遣い。
- 情報公開のスコープ。
- その他。
解決策
「ナレッジマネジメント」-- 社内外に向けた文書や素材の構造化、編集
- ナレッジマネジメント
-
不確実な世の中に立ち向かうためのナレッジマネジメント - Qiita
- 共同化(Socialization)、表出化(Externalization)、連結化(Combination)、内面化 (Internalization) この4つのプロセスをぐるぐると回すことで組織全体として知識を創造していくというのが知識創造スパイラルの全体像
- ”組織で使える知識”を創る、技術相談の「ナレッジマネジメント」実践 - LIFULL Creators Blog
- 社内の情報共有ツールを Qiita:Team から esa に乗り換えました - Feedforce Developer Blog
- フロー情報とストック情報を分ける~情報過多の時代を生き抜くために:ナレッジ!?情報共有・・・永遠の課題への挑戦:オルタナティブ・ブログ
-
不確実な世の中に立ち向かうためのナレッジマネジメント - Qiita
- 編集、加工
- 校正
- よりよい文書を書くための校正ツール「textlint」
- 例:
- 送り仮名(取り扱い/取扱い)
- 外来語(サーバー/サーバ)
- 略称(年次有給休暇/年休)
- 同じ意味だが機能名と、一般用語での差異(考課/評価)
- 用語の粒度(雇用保険担当者/社会保険担当者)
- 静的サイト
- その他
- テンプレート作成
- 教育コンテンツ作成
- ムービー作成
教育・ガイドラインづくり
- ツールやテンプレートについての教育
- ライティング講座
- 開発者がドラフトをうまく作成できるように教育
「DevRel」-- 開発者向け広報、社内外の技術情報収集、試用
- GitHub OrganizationリポジトリとTechblogなど色々
- https://twitter.com
- 国内
- 海外
- DevRel
- DevRelTokyo: https://twitter.com/devrelTokyo
- DevRelのカレンダー | Advent Calendar 2021 - Qiita
- SlackとIBMのエバンジェリスト/アドボケイトに聞いたDevRelの価値とは | Think IT(シンクイット)
- IBMのデベロッパーアドボケイトが考える開発者を支援する3つのCとは | Think IT(シンクイット)
- デベロッパーアドボケイトであるということ. 本記事は DevRel Advent Calendar 2019… | by Taiji | Medium
- DevRelで作る開発者の未来 - Speaker Deck
- DevRel Meetup Tokyoコミュニティでの技術書典5の参加報告 - Qiita
- イケてる事業のスタートアップに増えてきた「Devrel」とは? | Next Gate
翻訳、編集、既存文書のレビュー
- 様々な言語でやり取りされている状況で、文書でコミュニケーションができるようにサポート
- ローカライズ支援
関係:
各社事例
日立インフォメーションエンジニアリング
- マニュアル制作
- 製品・サービスのマニュアル制作
- 業務システムのマニュアル制作
- マニュアル改善コンサルティング
- システム導入時の操作研修
- 文章品質の向上支援(校正・校閲)
- ドキュメント制作トータル・ソリューション・サービス
- Web制作
- Webサイト制作/Webサイト保守
- SharePointサイト制作
- モバイル対応Webサイト制作
- グローバル対応Webサイト制作
- プロモーションデザイン
- プレゼン資料制作
- 動画制作
- カタログ/リーフレット制作
- イベントプロモーション
- GUIデザイン
- 操作フロー・画面設計
- アイコン・ビジュアルデザイン
- 翻訳
- 翻訳
- 中国語翻訳サービスのご紹介
- 英文・中文リライト
- ソフトウェアのローカライズ支援
- 英文・中文評価
- 教育・研修
- テクニカルライティング講座
- 技術文書の指導ポイント講座
- eラーニング教材制作
- eラーニングコンテンツの制作
- 画面操作ムービーの制作
- 設計ドキュメントの品質向上支援
LINE
LINEの社内には「テクニカルライティング」の専門チームがあります
テクニカルライター / Japanese documents
- サードパーティ向けにエンジニアが作成したドラフトをレビュー・再構築し、Webで閲覧できるように編集、加工
- 様々な言語でやり取りされている社内で、共通の文書でコミュニケーションができるようにサポート
- エンジニアがドラフトをうまく作成できるように教育(ライティングに関連するツールやシステムについての教育を含む)
- 社内外、利用者に向けた文書の構造化、編集
- 開発者向けのプロダクトの情報収集、テスト
- 作成された開発文書のレビュー、編集
- LINE Developers https://developers.line.biz/ で公開している文書の編集、管理
- LINE Biz Partnerに提供する文書の編集、管理
サイボウズ
- エンジニアと密なコミュニケーションを行い、サービスの仕様を把握する。
- 製品によって、仕様書は英語の場合もある。また、海外拠点のメンバーとの英語でのコミュニケーションも必要になります。
- プロダクトマネージャーとサービスの利用者のイメージをすり合わせて、適切なUI文言の選定、およびヘルプ記事の執筆する。
- 作成したヘルプ記事のレビューをプロダクトマネージャー、QAエンジニアなどに依頼し、受けたフィードバックを反映する。
- UI文言・ヘルプ記事の翻訳を、チーム内の翻訳者や翻訳会社に依頼する。
Amazon
Technical Writer (以下翻訳)
- 文章、口頭、視覚的なコミュニケーションスキルを駆使して、推奨プログラムのサポートを得る。
- あらゆるレベルの顧客と協力して要件やフィードバックを収集し、目的を定義して結果を出す。
- 技術的な内容の編集、ドキュメントの構造やプロセスの改善の提案など、チームメイトやお客様と協力してドキュメントの品質を向上させる。
- プロジェクト、課題、ソリューション、戦略について、リーダーやステークホルダーにプレゼンテーションを行い、会話をリードする。
- 優先順位付けを行い、組織のあらゆるレベルで明確なコミュニケーションをとる。
- プログラムスポンサーと協力して、プログラム戦略と主要なパフォーマンス指標を定義する。
- 大量のデータを見つけて分析し、コンテンツインテークチームが顧客に焦点を当てた意思決定を行うのに役立つ実用的なインサイトを作成する。
- プログラム指標に対する進捗状況を把握するための指標を導入し、進捗状況を毎月報告し、年間目標を設定する。
- ポートフォリオプログラムのドキュメント、ダッシュボード、コミュニケーション資料の作成と管理。
Apple
Technical Writer (翻訳)
- お客様の言葉で語りかけるような、明確でシンプルなコンテンツの作成。
- フォーマットやビジュアルでコンテンツを改善する方法を提案する。
- 同僚に建設的なフィードバックを与え、自分の仕事を他の人と一緒に確認する。
- さまざまなパートナーとのオープンで効率的なコラボレーション。
- コンテンツストラテジストとの協働により、パフォーマンスの低いコンテンツを分析し、改善方法を提案する。
- コンテンツプロジェクトを処理し、状況を積極的に伝える。
- 自分のコンテンツをより良くする方法を模索し、常に水準を高めていく。
Becoming a Technical Writer at Google (翻訳)
- 英語で明確に書く。私たちは、英語が第一言語であるか、第十言語であるかは気にしない。私たちが気にするのは、英語で書かれた文章の質だけである。
- 複雑な技術を比較的早く学ぶことができる。
- 複雑な技術を、対象となる人々にとって有益な方法で説明することができる。
- 強力な対人関係スキルを持っている。
- コードを理解することができる。
- 社内外のエンジニアを対象とした技術文書の企画、作成、維持管理。
- 他者が作成したドキュメントの編集、明確化、校正、およびライターではない人のライティングスキル向上のためのコーチング。
- 複雑なドキュメントプロジェクトを管理する。
- 関連するサンプルコードで開発者のドキュメントを補足する。
テクニカルコミュニケーター協会
各社まとめ
参考・リンク
テクニカルライティング基礎
比較 - テクニカルライティング・クリエイティブライティング
スタイルガイド
- 日本語スタイルガイド
- 日本翻訳連盟(JTF)日本語標準スタイルガイド
- 日本語文章のスタイルガイドのまとめ
- JTF日本語標準スタイルガイドのルールセットで文章をチェック
-
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい
-
Technical writing resources | Google Developers
- This style guide provides a set of editorial guidelines for anyone writing developer documentation for Google-related projects.
-
Welcome - Microsoft Style Guide | Microsoft Docs
- Welcome to the Microsoft Writing Style Guide, your guide to writing style and terminology for all communication—whether an app, a website, or a white paper. If you write about computer technology, this guide is for you.
-
Technical writing resources | Google Developers
学習
まとめ
以上、「テクニカルライティングチーム」が開発チームの一端として冒頭のような課題解決を担うには、どういったことが必要か考え、まとめた。参考になればさいわいです。