Google... - Qiita

Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい #初心者 - Qiita 5060 いいねしたユーザー一覧へ移動 5369 X（Twitter）でシェアする Facebookでシェアする はてなブックマークに追加する more_horiz 記事を削除する close 一度削除した記事は復旧できません。 この記事の編集中の下書きも削除されます。 削除してよろしいですか？ キャンセル 削除する delete info この記事は最終更新日から3年以上が経過しています。 @ yasuoyasuo ( 中野 ヤスオ＠ARI ) in ＡＲアドバンストテクノロジ株式会社（ARI） Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい 初心者 初心者向け 新人プログラマ応援 テクニカルライティング 5060 最終更新日 2022年10月13日 投稿日 2020年05月24日 はじめに エンジニアにとって、仕様書などの技術的な文章を書くこと（ テクニカルライティング とも言います）は避けて通れません。ただ20年来多くのエンジニアの方々と同僚として接してきて思うことは、エンジニアの方の中には「文章を書く」ということに苦手意識がある方が一定数いるということです。 でもこの「 テクニカルライティング 」のスキルは、才能というよりは一種の「技能」だと思うんです。ある一定の 原理原則 を理解して実践を繰り返すことで、 必ず一定レベルで習得できるもの だと著者は信じています。 もしこの テクニカルライティングの原理原則 をまだ体系的に学習したことがない、または過去学習したが改めて再学習したいという方に、お勧めのコンテンツを見つけたのでご紹介します。 https://developers.google.com/tech-writing Every engineer is also a writer. という一文で始まるこのコンテンツは、Google社が公開している テクニカルライティングの教育用資料 です。 テクニカルライティングの基本原則を、とても簡潔な文章と事例でわかりやすく紹介しています。そして何より嬉しいのが分量がコンパクトなんですよね！ 英語なのですが、読みやすい簡潔な英語ですし、Google翻訳などで十分に理解できます。英語が苦手な方にも負担は少ないと思います。（実際私も英語は得意ではありませんが問題なく読むことができました。） 何より、読みやすさとは言語の壁以上にその書き方や構成であることを身を持って表現しており、日本のエンジニアリング業界でより広く読まれて欲しいコンテンツだと感じました。 ここではこのコンテンツとそこで示されている基本原則を簡単にご紹介します。 コンテンツの構成 元々このコンテンツは初学者から教育者や職業ライターまでを広く想定されているようで、講義資料も事前学習用と講義（実践演習）用に分かれています。 この事前学習用コンテンツこそが、今回ご紹介したいものになります。 必要最低限の要素がとてもコンパクトにまとまっているんです！ その事前学習用コンテンツは2部構成（One＆Two）になっているんですが、以下それぞれの骨子と概要をなぞってみたいと思います。 Technical Writing One Technical Writing Oneは、より明確な技術文書の書き方を教えています。 https://developers.google.com/tech-writing/one 目次はこちらです。 それぞれ各項目毎に説明コンテンツがあります。 最後のSummary（要点）部分を抜粋します。 ※以下の翻訳はGoogle翻訳をもとに著者が訳したものです。誤訳あれば訂正しますのでご指摘ください。 用語は文書内で一貫性をもたせる 曖昧な代名詞の利用は避ける 受動態は避け、能動態を優先する 強い動詞を選択する 1 曖昧な動詞よりも意味が限定される動詞を選ぶ 1文1メッセージ 長い文章はリスト形式に変換する 不要な言葉は排除する 順序が重要な場合は番号付きリストを使用し、順序が重要でない場合は箇条書きリストを使用する リストを使う場合は言葉の並列性を保つ 番号の付いたリストは命令語で始める リストと表を適切に使う 段落の骨子を示す良いリード文を作る 1段落1トピックに絞る 読み手に伝えるべきことを定義する 読み手を意識して書く ドキュメントの最初にそのドキュメントの重要なポイントを明確に示す 総じて言えば以下の2点が重視されていると言えるでしょう。 読み手を定義し常に読み手目線におくこと 読み手が極力読み違いや誤解を避けるように簡潔でわかりやすい記述にすること Technical Writing Two テクニカルライティング2は、技術者がテクニカルコミュニケーションスキルを向上させるのに役立ちます。 https://developers.google.com/tech-writing/two 目次はこちらです。 1と同じくそれぞれ各項目毎に説明コンテンツがあります。 最後のSummary（要点）部分を抜粋します。 スタイルガイド（テンプレート）を採用する 読み手がどう思うかを考える 書いた文書を（自分自身で）声に出して読んでみる 下書きを書いた後少し寝かせてまた読んでみる 優れたレビュワーを見つける ドキュメントのアウトラインを作るか、または自由に書いた後にそれを整理する ドキュメントの対象範囲と前提条件を最初に示す できるだけタスクベースの見出しにする （一気にまとめて出すのではなく）情報（新しい概念や指示）は小出しにする イラストを作成する前に、説明書きを書いてみる 1つの図面内の情報量を制限する キャプションで要点を説明するか、画像に注意を惹くマークを追加して、画像または図の適切な箇所に読者の注意を向ける 理解しやすい簡潔なサンプルコードを作成する コードのコメントは短くするが、簡潔さよりも明快さを優先する 自明なコードにコメントは書かない コメントは、コード内の直感的でない部分を明らかにすることに集中させる 良い例だけでなく、良くない例も提供する コードサンプルは複数の複雑さを想定したものを提供する 継続的に見直すことを実践する ユーザーによってそれぞれ異なる資料形態を提供する 読者がすでによく知っているものと比較する チュートリアルでは、複数の例を使用して伝えやすくする チュートリアルでは、読者がつまづきやすい点を指摘する Technical Writing Oneは主に各文や文章における情報伝達の最適化にフォーカスしていているのに対して、Technical Writing Twoはそのドキュメント（コンテンツ）全体として目的達成最大化のための原理原則を示しています。特に技術文書の場合は、図やサンプルコードを利用することが有意義な場合が多いので、その利用の留意事項も記載されています。 まとめ 以上Google社が公開している テクニカルライティングの原理原則 を示したコンテンツを紹介しました。 個人的には何度となく「 audience 」という単語が出てきたのが印象的でした。 言語や用途は問わず、「 読み手が求めているものを読み手がわかりやすいように書く 」ことが、文章を書く上で一番大切なことなのだと痛感しました。全部のコンテンツを翻訳しながら読んでも1~2時間ほどで読めるかと思いますので、テクニカルライティング力を強化したいという方は、是非一度目を通してみてください。 その他参考リンク その他テクニカルライティングに関する参考記事や書籍 ドキュメント作成スキル向上を目指す人向けおすすめ記事まとめ - Qiita 私のまとめ記事ですが、「文章術系」リンクの箇所に、テクニカルライティングスキル獲得に役立つ書籍やコンテンツのリンクをまとめています。いずれもおすすめのものばかりなので一度覗いてみて下さい。 ドキュメントスタイルガイドライン Google社、Microsoft社のドキュメントスタイルガイドラインです。 その詳細度や範囲は圧巻ですが、ここまで定義することでしか品質の統一化は図れないのだろうなぁとは思います。 https://developers.google.com/tech-writing/resources のページでも紹介されています。 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. 強い動詞とは？→意味が明確になる動詞。 https://developers.google.com/tech-writing/one/clear-sentences ↩ 5060 いいねしたユーザー一覧へ移動 5369 comment 18 コメント一覧へ移動 新規登録して、もっと便利にQiitaを使ってみよう あなたにマッチした記事をお届けします 便利な情報をあとで効率的に読み返せます ダークテーマを利用できます ログインすると使える機能について 新規登録 ログイン 5060 いいねしたユーザー一覧へ移動 5369 more_horiz 記事を削除する close 一度削除した記事は復旧できません。 この記事の編集中の下書きも削除されます。 削除してよろしいですか？ キャンセル 削除する delete