Technical Writing: How to Write Software Documentationを修了したので、まとめ

修了した

ポイント

Learn a proven strategy for writing software docu in GitHub wiki based on the 12 main principles of technical writing!

受講ノート (章は記載を割愛しているところもあります)

先生: https://www.udemy.com/user/jordanstanchev/
コース: https://www.udemy.com/course/start-your-career-as-user-assistance-developer/
コースとは関係ない先生のスライド: https://github.com/JordanStanchev/Getting-Started-as-User-Assistance-Developer

1-1. 何を学ぶか？

テクニカルライティングの様々なタイプ

• 機能的
• タスクオリエンテッド
• 成果物でも何でも

1-2. テクニカルライティングとは？

• 情報伝達のプロ？
• 特定のソフトウェアの使い方をより良く理解するためのファシリテーター。
• 情報の作成
• 情報の見せ方 グラフィック インフォグラフィック ビジュアル 特殊なビデオの作り方、製品の使用方法

1-3. テクニカルライティングをするのは誰？

テクニカルライターの原則
異なる職種での出来事
コンテンツ管理システム
作業指示書
パブリッシングに移行する

• ユーザーアシスタントは、ユーザーを支援することを目的としています。
• 情報アーキテクチャは、顧客を支援する

1-4. テクニカルライティングから得られる成果とは？

• ユーザーガイド マニュアル
• クイックスタートで簡単に製品を使い始める
• ソフトを正しく使う
• インストラクションビデオ

1-5. テクニカルライターの仕事

「書く」だけではない

• 企画
• 準備
• 作成
• 構造化、組織化
• 分類する
• 提供し、メンテナンスする

機能別ドキュメンテーション

SAP Cloud Platform Launchpad（ローンチパッド）
Launchpadとは？
例: https://help.sap.com/viewer/8c8e1958338140699bd4811b37b82ece/Cloud/en-US/5a293715014342ffacaa4726f0fb7196.html

1-9. ソフトウェアドキュメンテーションにおける機能的文書化

• 機能的なドキュメントは時間をかけてはいけない
• シンプルで簡単に使えることが目的
• 「New」ボタン、だけではわからない
• よくできたドキュメントとは、ソースコードにおける「コメント」のようなもの。
• UXはとても重要で、使い勝手の良いソフトウェアは、まさに私たちがすべきことである。

1-10. 機能的なドキュメントを書くための戦略

• 1画面目から始める。
• ページとその用途を説明する。
• 顧客が画面上で見るものを記述する。
• ユーザーインターフェース（UI）に表示される順番にコンテンツを整理する。

1-11. タスク・オリエンテッドなドキュメント

• 製品の高度な使用方法について達成する。
• タスク・オリエンテッドは結果を出すこと。
• お客様が購入された理由、目的を達成する。

1-12. タスク指向のドキュメントを書くための戦略

• 顧客が実行する必要のあるタスクを特定する。
• 論理的な順序で並べる。
• お客様が知るべき概念や情報を補足する。
• 製品をよりよく理解するために、後々役立つ参考情報を追加する。
• 論理的順序

1-13. タスク・オリエンテッドなドキュメントの例

• 製品がシンプルであればあるほど、提供するドキュメントは少なくなる。
• 前提条件が明確であること。

1-14. ソフトウェア・ドキュメンテーションとは？

「ここをクリックすると何が起こるかわかる素晴らしいツール」
"おっと、どうすればいいんだ？" をなくすもの

1-15. ソフトウェア開発の世界におけるテクニカルライター

• ユーザーが効果的にソフトウェアを設定し、使用できるように支援する。
• ユーザーが自分で問題を解決できるように支援する。
• お客様に喜んで使っていただくため、ソフトウェア開発チームにとって開発チームの時間と労力を節約する。

1-16. ソフトウェアに関するテクニカルライティングの成果物

• ユーザーガイド
• APIドキュメント
• 親切な説明書、画面
• 説明用動画または画像、音声による説明
• 検索のために機械に提供されるメタデータ

1-17. ソフトウェア開発チームにおけるテクニカルライター

• 実際にお金を払うのはお客様
• UIをデザインする
• 開発者
• 要求事項を収集・整理する

1-18. テクニカルライティングのプロセス

• 調査・情報収集
• ダンプ情報をすべて書き出す
• 情報原稿の構成と整理を開始する
• 関係者に発表し、フィードバックを収集する
• フィードバックを文書に反映させる 最終的な納品を準備する
• 出版する
• 顧客フィードバックの収集とメンテナンス

3-35. テクニカルライティングにおけるスタイルガイドの活用法

• スタイルガイド、または文章を書くための基準や指針
• 使うべきスタイルが違う
• 文脈に合わせるための文書
• 親しみやすい人向け
• ビジネスソフト、従業員の給与計算、文脈に応じた公式なスタイルと言語
• ブランディングガイドライン
• お客様の目の前で、ユーザーに対して、会社のイメージを伝える
• それは顔

3-36. スタイルガイドとは？

• スタイルガイドとは何か？なぜテクニカルライティングで文体を気にする必要があるのか？
• ソフトウェアのドキュメントを書くために、すでに再利用できる一般的なスタイルガイドはどれか
• ソフトウェア文書作成で適用しなければならない一般的なスタイルルールは何か？
• スタイルガイドのルールを自社でどこまで適用すべきか。

3-37. なぜ、文章を書くための基準が必要なのか？

• ブランディングの理由 - 文体を企業ブランドと一致させること
• ユーザーから見て、一貫性があり、明確に認識されるようなコンテンツを提供したい。
• ターゲットユーザーに明確な情報を提供するためのルールを定義する。
• 商品の品質や満足度を高めることができる。

書き方のガイドラインを定義する
- 見出し THIS IS A HEADING

- 段落 空の段落を挟んで
- セクションも可 文体、太字、末尾にフルストップなし
- 箇条書きのリスト
    - パラ1
    - パラ2

- 番号付きリスト
1.
2.
3.

オックスフォード大学スタイルガイド
https://www.ox.ac.uk/sites/files/oxford/media_wysiwyg/University%20of%20Oxford%20Style%20Guide.pdf

略語、短縮形、頭字語
大文字小文字、構造、簡素化、ユーザビリティ

• 見出し
• 段落
• セクション
• テーブル
• 箇条書きリスト
• 番号付きリスト

ポジティブ表現

OK: 通知を受け取るには、コードを入力してください
NG: 名前を入力しないでください

3-40. 誰がルールを必要としているか

• ユーザー支援開発者（テクニカルコミュニケーターまたはテクニカルライター）
• コンテンツ編集者
• 翻訳者
• ソフトウェアアーキテクト
• プロダクトオーナー
• ソフトウェア開発者
• ユーザビリティ・エクスパート(UX)

3-41. スタイルガイドの活用による成果

• よく整理されたコンテンツ
• シンプルさ
• 簡潔さ
• 正確さ

3-42. 文章における構造

• 良い構成/構造
• 内容を論理的に構成する。どのように構成するかに注意する。
• 見出し
• 段落
• セクション
• テーブル
• 箇条書きリスト
• 番号付きリスト

3-43. 簡潔さ

• 冗長性を避ける
• テキストをコピーするのではなく、情報へのリンクを貼る
• 視覚的補助（図、図式、スクリーンショットなど）の使用

3-44. 簡略化

• 簡単な言葉や文法を使用する
• 短い文章を使用する
• 肯定的な表現を使用する。
• 互いに修飾し合う長い名詞の連続や、長い命題の句の連続は使わない。その代わり、管理しやすい小さなパーツに分割する。 アメリカ英語を使う。

3-45. 精度

• 真実の情報を書く。
• 正しい用語と一貫性のある用語を使用する。
• 正しいナビゲーションパスを使用する。
• 正しい製品名または部品名を使用する。
• コストをかける。
• ダブルチェックする。

3-46. 動詞の選択。Can か May か？

OK: 「変更」「保存」「削除」「インポート」「作成」...
NG: 「メンテナンスする」

• 可能か不可能か？
• できる = ユーザーまたはシステムにとって可能である。
• Mayまたはmight = 可能な状態または結果についてである。

3-47. 動詞の選択。しなければならない/してはならない/すべき/してはならない/してもよい

• MUST = 絶対条件
• MUST NOT = "shall not" - 絶対的な禁止事項
• SHOULD = 「推奨する」 正当な理由が存在する場合もある
• SHOULD NOT = "推奨しない"
• MAY = "任意" 選ぶことができる。

3-48. 能動態と現在形

• 能動態を使用する
• テキストの種類と文脈が適切であれば、"you" を使ってユーザーに直接語りかける。
• 誰が何をするのか（ユーザー、アプリケーション、システム管理者）を明確に定義する。

3-49. 専門用語

• POを持つ開発者とともに、用語について議論する。UIデザイナー。
• 正しい用語と一貫性のある用語を使用する。
• 独自の用語や専門用語の考案に注意する。
• 同じ単語を異なる意味で使用しない : 「アンブレラ用語」

3-50. 追記

• 短縮形(don't can't
• ユーモア
• 性別 ユーザーの性別を決めつけない。"He or She" を使う。
• 専門用語や慣用句

3-51. ツールを使う

• スペルチェッカーを使う
• ウェブ上で既存の用語/表現を検索する

演習: https://github.com/JordanStanchev/Getting-Started-as-User-Assistance-Developer

リンク: https://jpdocu.teachable.com/

7-112. グラフィックスを作成するためのツール

• MS Power Point
• Google Slides
• https://app.diagrams.net/
• https://www.easel.ly

8-121. なぜ情報アーキテクチャにこだわる必要があるのか？

自問自答してください。

• あなたのドキュメントは、インターネットで検索されるようにしたいですか？
• 異なる成果物の中でドキュメントを再利用できるようにしたいですか？
• 著者が異なるプロジェクトで働けるようにしたいですか？
• 新しいプロジェクトに参加する際の学習曲線を短くしたいですか？

8-122. テクニカルライティングにおける情報アーキテクチャ

• 一貫したワークアウト環境を提供する
• 再利用を可能にし、定着させる
• 著者の相談に乗り、組織やドキュメンテーションに関する問題の解決を支援する。

8-123. コンテンツに情報アーキテクチャの原則を適用するには？

• 対象ユーザー
• 消費パターン
• 製品規格
• 更新サイクル
• 納品物

などをカテゴライズしていく。レシピを思い浮かべるとわかりやすい。
分類法は生物学にも由来する。

• お客様第一
• 標準規格
• 納品物
• 納品経路
• 論理的に整理する
• コンテンツの再利用
• 組織パターンの特定

受講のきっかけ

Udemyのお得キャンペーンに乗じたところでしたが、体系的に理解できました。
以上です～。