実践テクニカルライティング - 開発者が「外国語」を使うときの言語技術達3つ

言語技術 というものをご存知でしょうか。

言語技術とは、思考を論理的に組み立て、相手が理解できる様に分かりやすく表現すること。
人前で話す能力や議論の能力、文章を書く能力や論文を書く能力はトレーニングによって身につけられる。我々開発者にとっても、普段の語彙に距離のある相手、たとえば非技術者との会話の際にこの言語技術を意識することがキーになる。記事のタイトルは「外国語」と書いたが、英語は勿論、開発者にとって顧客や非技術者は時として「外国人」。開発者にとって、例えば

• 英語学習
• テクニカルサポートのやり取り

の時等に使える、情報を整理する言語技術とツールについて、3つのトピックからまとめた。

1. 『外国語を身につけるための日本語レッスン』に学ぶ、言語技術
2. 『情報を整理するたった5つの方法 LATCH』
3. Google Sheets 等で、「外国語」を使う相手と状況共有をうまくする仕掛け

1. 『外国語を身につけるための日本語レッスン』に学ぶ、言語技術

言語の異なる相手と離すのと同じように丁寧な情報の整理が求められる。まずは 言語技術『外国語を身につけるための日本語レッスン』 から考え方をサマリする。

例:「Googleカレンダーの使い方を教えて」。
ユーザーにアプリケーションの使い方をどう教えるかを考える。「言語」のことなる相手に、問合せにどうテクニカルサポートをするかということ。

アンチパターン

アンチパターン.md

あなたはGoogleカレンダーを知っている？
じゃあアプリをまずインストールします。
それでスケジュールを作成します。
それからチームメンバーとマネジャを招待して、会議の予定はできあがり。
それから時間になったらオンライン会議に入室してくださいね。簡単ですよ。

上の場合に、言語を共有しきれていない相手からは以下のようなさらなる質問が発生することが予想される。

さらなる質問.md

Googleカレンダー？どこからインストールするの？
スケジュール？どこからできるの？
チームメンバーの名前はどこから探せるの？
招待って、彼らに連絡を取らないといけない？
オンライン会議ってスマホから？

改善例

これを言語技術原則に則って考える。以下例。

こうしたい改善例.md

Googleカレンダー:
- Android、iOS、いずれでもアプリとしてインストールできる。
- PCでもブラウザから利用可能。
- アクセスすると、基本的なヘルプメニューがあるのでそちらを参考に。

スケジュール作成:
- 日付をクリック。
- 招待したい人のメールアドレスなどで、検索。
- こちらも詳細設定はヘルプを参考に。

オンライン会議手順:
- 予定日時に、スケジュールを開くとオンライン会議ツール "Google Meet" が利用可能。 

すべてを説明しようとすることが答えではなく、ほかを参照せよと誘導することも技術である。

言語技術の使い方

多くの国々では「言語技術」を国語の教科の中で学ぶ。一方日本では国語は「文学教育」に重きを置きがち。これが日本人が外国語を学ぶ際の障壁である。日本語的発想で書いた日本語は英語などに翻訳しても外国人には理解してもらえない。つまり我々開発者が開発者的発想で書いた文書も、非技術者にそのままは理解してもらえないということ。

言語技術は以下に分類される。

1. 説明の技術
2. 描写の技術
3. 明確にいう技術
4. 質問の技術
5. 返答の技術
6. 分析の技術

とりわけ 1. 説明の技術 が技術の軸になります。詳細を見ると以下。

1. 概要から詳細へ … これが大原則
2. 空間的秩序 … 上から下、縦書きなら右から左・横書きなら左から右、手前から奥、外から内。
3. 時間的秩序 … 1. まず、次に、最後に。2. 連番
4. 情報の整理 … 上の1. 2. 3を整理する。
5. 客観的な表現 … きれい、かっこいい 等は使わない。
6. 情報の受け手の設定 … ペルソナを理解して言葉を選ぶ。

参考

原文日本語文書の分かりやすさが、翻訳の品質と工数も左右するという点で、もう一冊。[『技術翻訳のチェックポイント』] ( https://www.maruzen-publishing.co.jp/item/b293231.html) では以下のように説明されている。

英語品質を向上させる日本語文書の執筆
ガイドラインに沿って翻訳者が訳しているにもかかわらず、 時折品質の悪い翻訳に遭遇することがあります。 このような問題の最大の原因は、原文の日本語文書の中にあります。

• 原文の日本語文書がテクニカルライティングの基本原則に反している。
• 問題の修正に要するリライトのレベルが翻訳者としての業務以上のものである。

日本語の図が複雑で分かりにくければ図中の表示語句が正しく翻訳されていても、
英語の図もまた複雑で分かりにくいものになります。英語文書中の問題は、
翻訳者ではなく、原文の日本語文書に起因しています。

日英翻訳において英文を向上させるには和文筆者が原文の日本語文書をテクニカルライティングの標準原則に相反しないように書くべき、となる。

2. 『情報を整理するたった5つの方法 LATCH』

以上を踏まえて2つ目、「情報デザイン」にもかかわる『The Only Five Ways to Organize Information (Five Hat Racks or LATCH) LATCH (情報を整理するたった5つの方法 LATCH)』という5原則の考え方がある。

• Location（場所）
• Alphabet（アルファベット）
• Time（時系列）
• Category（カテゴリ）
• Hierarchy（階層）

気にかける必要があるのはたった5つ。頭文字をとってLATCH。Location（場所）、Alphabet（アルファベット）、Time（時系列）、Category（カテゴリ）、そして Hierarchy（階層）。

情報整理の必要性に直面したときは、これらの5つの方法を考えて、最良のものを選ぶ（または複数選択する）ことをお勧めする。以下が、情報を整理する5つの方法のそれぞれの説明と例。

Location（場所）

「物理空間の視覚的な描写」を示すことで、情報を整理する。

引用: 『The Only Five Ways to Organize Information (Five Hat Racks or LATCH) 』

• 例えば地図は場所別に整理する一般的な方法。
• ショッピングモールのディレクトリや大学のキャンパスマップ等。
• 通常、ある種の領域または位置を、視覚化する。

Alphabet（アルファベット）

アルファベット順に整理する。

引用: 『The Only Five Ways to Organize Information (Five Hat Racks or LATCH) 』

• 人々が特定の用語やトピックを知っているときに効果的。ここで重要なのは、読者/聞き手の双方が用語を知っていて、辞書の裏の索引や辞書のように検索するものがあるということ。
• 一方例えば生物学を学ぶ際に、その細胞の名前を知らなければ、アルファベットは機能しない。用語が聞き手にとって意味をなさない場合はこのアルファベット順は使えない。
• あるいはこのアルファベット順はフィクション小説における筆者の姓名順には適するが、ノンフィクションを同様に並べてもうまく機能しないかもしれない。

Time（時系列）

時系列に整理する。

引用: 『The Only Five Ways to Organize Information (Five Hat Racks or LATCH) 』

• 例えば「人類の発明の歴史」などという、年代順のパターン。イベントが起こった年によって情報を見つけるという際に便利である。
• あるいは一定の時間内に物事がどのように起こるかを示すのにも良い。例えば料理の作り方のように、サイクルの始めから終わりまでの過程を記述したフローチャートを考えてみることができる。

Category（カテゴリ）

「カテゴリ」は、さまざまな動物の種類の説明や食料品など、さまざまな目的に役立つ。

引用: 『The Only Five Ways to Organize Information (Five Hat Racks or LATCH) 』

• 情報を整理する5つの方法のうち最も幅広い。
• 食品に関する情報をどのように表示するかをイメージしてみる場合、色、形、性別、モデル、価格など。これにより何でも情報を整理できる。

例

• 一般から特殊
• より重要ではないことをもっと重要
• 比較とコントラスト
• 問題 - 方法 - 解決策
• 原因と結果

Hierarchy（階層）

「階層」は、ある情報が重要度または順位の順に他の情報とどのようにつながっているかを示すときに役立つ。

引用: 『The Only Five Ways to Organize Information (Five Hat Racks or LATCH) 』

• 例えば組織図では階層を使用して表示する。 規模の大きいものから最小のもの、最も重いものから最も軽いものまでを表示するためにも使用できる。

ここまでが2つ目。最後は応用。

3. Google Sheets 等で、「外国語」を使う相手と状況共有をうまくする仕掛け

例: 数往復のやりとり後「これは長引きそうだ...」と直感するトラブル要請と出会う。

アンチパターン

以下、現場の顧客付と開発の会話例。

アンチパターン.md

現場「〇〇が起こりました」
開発「ログください」

現場「〇〇が必要です」
開発「ログください」

現場「〇〇でエラーが出ているみたいなんですけど」
開発「ログください。というかいつまでに解決が必要ですか？」

中略、

開発「〇〇フラグをほげほげしてください。」
現場「えっとそれって何見れば（涙」

開発「んー、ちょっとこれ〇〇チームの応援が必要だから」
現場「えっとそれって誰に（涙」

果たしてどうすれば簡単に経緯を共有できるか。

改善例

Spreadsheet を業務利用する時、この５つだけは押さえておこう が参考になる。
具体的には以下ステップ。

1. Spreadsheetを全員共有で作成。
2. 冒頭３行で誰にでもわかるタイトルとゴール、できれば、わかっていること、達成したいことを書く。
3. 既に試した（試したい）こと（現象）、それに対する事実、考えられる仮説を３列で書いていく。

以下具体例。

冒頭: 状況サマリ

本文: 事実と仮説を明確に区別する

これだけ？

基本はこれだけ。見ての通りフォーマットもだいたいで大丈夫。しかし大事なのは調査に関わる全員が時系列を超えて事実と仮説を一発で把握できること。
不具合報告の書き方参考リンク、良い質問とはなにか 等も。

おまけ: ドキュメントの書き方

基本的なツール群。
質の高い技術文書を書く方法
Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい
ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ
LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた
テクニカルライティングについて学ぶぞ

比較 - テクニカルライティング・クリエイティブライティング
また、文章校正には 文章推敲ツール も参考に。

追記:

おまけ: テクニカルコミュニケーション参考文献(英語)

• I'd Rather Be Writing - exploring technical writing trends and innovations(英語)
  • http://idratherbewriting.com/
• テクニカルライティングのための基礎書 40(英語)
  • http://idratherbewriting.com/2010/09/10/40-foundational-books-for-technical-writing/
• ユーザ中心のドキュメンテーション原則(英語)
  • http://idratherbewriting.com/fles/user-centered-documentation-principles/#/
• Write the Docs(英語)
  • http://podcast.writethedocs.org/
  • https://twitter.com/WriteTheDocsATX
  • https://www.meetup.com/WriteTheDocs-ATX-Meetup/
  • http://idratherbewriting.com/2017/06/08/write-the-docs-presentation-navigation-best-practices/
  • https://www.youtube.com/playlist?list=PLZAeFn6dfHpkBld-70TsOoYToM3CaTxRC
• Docs Like Code(英語)
  • https://www.docslikecode.com/
• Just Write Click(英語)
  • https://justwriteclick.com/
• Review: Modern Technical Writing (英語)
  • http://idratherbewriting.com/2016/07/26/modern-technical-writing-review/
• Wikiversity of Technical writing(英語)
  • https://en.wikiversity.org/wiki/Technical_writing
• Technical communication Mike Markel(英語)
  • https://www.amaion.com/Technical-Communication-Mike-Markel/dp/1457673371/ref=dp_ob_title_bk

まとめ

情報をいかに整理するかはソースコードのリファクタリングに似た作業に思えます。
どうカテゴライズするか、テクニックを理解することで、より円滑に「外国語」話者、あるいは非技術者とのやり取りを行って問題解決をスムーズにしていきたいです。

以上3つ、参考になればさいわいです。