More than 1 year has passed since last update.

テクニカルライティングチーム、開発文書部、DevRelのお仕事 2021年12月版

Last updated at 2021-12-06Posted at 2021-03-12

テクニカルライティングチームの仕事についてまとめる。テクニカルライティングチームを作りたい開発チームを想定し、「テクニカルライティングチーム」の役割を概観する。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
- フロー情報とストック情報を分ける～情報過多の時代を生き抜くために：ナレッジ！？情報共有・・・永遠の課題への挑戦：オルタナティブ・ブログ
編集、加工
校正
- よりよい文書を書くための校正ツール「textlint」
- 例：
  - 送り仮名（取り扱い/取扱い）
  - 外来語（サーバー/サーバ）
  - 略称（年次有給休暇/年休）
  - 同じ意味だが機能名と、一般用語での差異（考課/評価）
  - 用語の粒度（雇用保険担当者/社会保険担当者）
静的サイト
- 静的サイト界隈の3文字アルファベットの整理とそのSSG達 (Hexo、Hugo、Jekyll、GitBook、Gatsby、VuePress、Docsify)
その他
- テンプレート作成
- 教育コンテンツ作成
- ムービー作成

教育・ガイドラインづくり

「DevRel」-- 開発者向け広報、社内外の技術情報収集、試用

翻訳、編集、既存文書のレビュー

様々な言語でやり取りされている状況で、文書でコミュニケーションができるようにサポート
ローカライズ支援
- アプリをローカライズする時の見積もり - 翻訳外注

関係：

各社事例

日立インフォメーションエンジニアリング

テクニカルコミュニケーション

マニュアル制作
- 製品・サービスのマニュアル制作
- 業務システムのマニュアル制作
- マニュアル改善コンサルティング
- システム導入時の操作研修
- 文章品質の向上支援（校正・校閲）
- ドキュメント制作トータル・ソリューション・サービス
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 (以下翻訳)

文章、口頭、視覚的なコミュニケーションスキルを駆使して、推奨プログラムのサポートを得る。
あらゆるレベルの顧客と協力して要件やフィードバックを収集し、目的を定義して結果を出す。
技術的な内容の編集、ドキュメントの構造やプロセスの改善の提案など、チームメイトやお客様と協力してドキュメントの品質を向上させる。
プロジェクト、課題、ソリューション、戦略について、リーダーやステークホルダーにプレゼンテーションを行い、会話をリードする。
優先順位付けを行い、組織のあらゆるレベルで明確なコミュニケーションをとる。
- プログラムスポンサーと協力して、プログラム戦略と主要なパフォーマンス指標を定義する。
- 大量のデータを見つけて分析し、コンテンツインテークチームが顧客に焦点を当てた意思決定を行うのに役立つ実用的なインサイトを作成する。
プログラム指標に対する進捗状況を把握するための指標を導入し、進捗状況を毎月報告し、年間目標を設定する。
ポートフォリオプログラムのドキュメント、ダッシュボード、コミュニケーション資料の作成と管理。