ドキュメントを「分解」して生活を始める方法

今日は、機能しないドキュメント、ある種の遺産、整理されていない、ブランドのアイデンティティに対応していないドキュメントを取り除く方法についてお話しますが、そこには何がありますか-単に悪いドキュメントです。 その後、適切で有効な、論理的に整理されたブランドアイデンティティ文書を準備および再編成します。 そして、ドキュメントを取り除くとすぐに、すべてがバラ色で美しくなります。



GoogleのテクニカルライターであるAlexandra WhiteによるWrite the Docs Prague 2018カンファレンスでのレポートの翻訳です。2019年4月26日の1週間後、AlexandraはKnowledgeConfカンファレンスで「説得力のあるマルチメディアドキュメントを作成する方法」で講演します。 アレクサンドラは、マルチメディアフォーマット（ビデオ、オーディオ、gif）をアーティファクトとパッケージング知識の作成プロセスに統合する方法、マルチメディアフォーマットが最適で動作しない場合、マルチメディアアーティファクトの有効性を測定し、その制限を克服する方法を説明します。

まず始めに、自分自身、私が知っていること、その方法についてお話しします。 私の名前はアレクサンドラ・ホワイトです。私はニューヨークに住んでいて、テクニカルライターであり、それ以前はテレビ会社でウェブ開発者として働いていました。 そこでは、5、10、15年働いた人々が、コードがどこにあるのか、どのように機能するのかについての大量のレガシー情報に囲まれていました。



仕事に就き、情報を見つけ、エンジニアに質問を延々と聞かなければならなかった。 長い時間がかかったので、コード内のコメントを促進し、関連するREADMEを書き始めました。その後、クラウド会社Joyentでの仕事になりました。

Joyentに来たとき、クラウドストレージについてはほとんど知りませんでした。主要な人気用語は会議で聞いたものです。 私が製品について知らないときに、私たちの製品の使い方を人々に伝えるのは奇妙だろう。 したがって、「2倍の速度で実行する」必要がありました。 これらのタスクがエンジニア、テクニカルサポートチーム、およびプロダクトマネージャーによって実行されるまで、今後8か月間、私はプロジェクトで唯一のテクニカルライターおよび編集者でした。 彼らは最善を尽くしましたが、優先順位の枠内でした。

私がプロジェクトに来たとき、混Toがそこに君臨したことを認めよう。 ギャップを埋めるために、できる限り迅速に作業を試みました。 たとえば、製品の操作を開始するためにコンテナの操作を開始する方法に関する入門ドキュメントがありませんでした。これが最初の電話でした。 私は、主力製品であるTritonのDocker入門手順に取り組み始めました。

最後に、私がこの緊急のタスクから抜け出すことができたとき、どうやら製品を理解し始め、好きなビジネスを始めました。古いドキュメントを「破壊」し始めました。



今日は、それを行う方法、古いものを破壊して新しいものを構築する方法、費用、コンテンツ戦略とスタイルガイドを作成した方法、そしてボーナスとして、状況があなたの側になく、仕事に障害がある場合の対処方法を教えます。

また、プロジェクトの作業を開始したときに考慮していなかったことを共有します。これにより、作業を計画するときにすぐにすべてを正しく実行できます。

プロジェクトの作業を開始した2016年8月、私はコンテンツの監査を実施しました。 私は仕事の年の間にそれらのほとんどについてさえ知りませんでした。 そして、ドキュメントの書き方についての単一の説明はなかったので、情報を見つけるのに多大な努力が必要であったか、これらの各サイトの非常に洗練された作業方法を知る必要がありました。

さらに、誰かがドキュメントを公開し、それを忘れてしまったために生じた巨大な技術的負債を発見しました。

まず最初に、私が見つけたドキュメントのあるサイトの数を示します。 適切なドキュメントを見つけるのが難しい場合は、Google検索を使用します。 そこで、私は指を交差させ、見つかった情報が正しいことを望みました。 当社のサイトの多くは許可により閉鎖されているため、これは最善の解決策ではありませんでした。



はい、当社のエンジニアでさえGoogleを使用して適切な製品情報を見つけています。 これが問題です。

したがって、 最初のリポジトリはwikiであり 、システムオペレータとサポートチームによって管理されています。 すべてのドキュメントの中で、これは最も関連性がありますが、承認によって閉じられており、その中の情報の検索はサポートチームの秘密であり、彼らは共有したくありませんでした。



別のリポジトリはJIRAチケットトラッカーです。



さまざまなバグレポートがそこに保存され、エンジニアとサポートチームのメンバーは、これらのバグを修正する方法、特定の問題を解決する方法を説明しましたが、情報はこれらのチケットに残り、公開ドキュメントには決して含まれません。

また、ソースコードの単一のソーステクノロジを使用して作成されたAPI ドキュメントのあるサイトもありました。 それは素晴らしいです、それはまさに私が目指しているものです-ドキュメントは可能な限りコードに近いです。



ただし、実際には、コードはそれに対応するドキュメントよりも速く更新されました。



最後に、 製品ブログがありました 。 あなたはおそらくブログがマーケティングだと言うでしょうが、いや、それは非常に深い技術文書、統合の説明、概念的なレビューを公開しました。 ところで、ここに彼女がいます。



これは、ユーザーがサポートを得て、クラウドストレージの仕組みを理解できる主要な場所となるはずです。 しかし、残念ながら、このドキュメントはエンジニアではなく製品チームによってサポートされていました。 私たちのエンジニアの中には、このウェブサイトの存在を知らない人もいました。 また、これは公開文書です。



だから私たちはおびえています。 ドキュメントのライフサイクルはありません。 ドキュメントは公開されています-素晴らしい、それについて考える必要はもうありません。すべてが整然としています。 これが問題です。 コンテンツは、Joyentの1つの声だけでなく、技術サポート、エンジニア、プロダクトマネージャーなど、さまざまな声で作成されました。 各利害関係者には、自分の意見、文書の見た目と配置場所に関するビジョンがあります。

さらに、ユーザーが正確に必要なものをよりよく理解するために、ユーザーがそれをどのように読んでいるか、彼らが探しているものを理解するためにこのウェブサイトをテストした人はいません。

しかし、どんな混乱も修正できます。少なくとも2つの方法があります。整理するか、最初から始めるかです。

テクニカルライターとしての私たちの仕事は、ユーザーがパニックの瞬間に問題を解決するか、製品をより効率的に使用するのに役立つ小さなものを見つけるかどうかにかかわらず、ユーザーが質問の答えを見つけることです。 そして、私たちの仕事は、同僚がより良い文章を書くのを助けることです。 私たちはすべての専門家になることはできません。 特定の分野の専門家、つまり特定の分野の専門家に頼って、ユーザーが知っておくべきことをユーザーが理解できるようにします。

テクニカルライターは羊飼いです。 ユーザーと同僚を答えと実用的なソリューションに導きます。 そして、時には最良の解決策は最初から始めることです。 しかし、既存のインフラストラクチャに多くの投資を行った後、すべてを地面に焼き付けることは、利害関係者にとって危険を伴うようです。

良い議論が何であり、どれほど重要かを理解することが重要です。 私はこれを子供として理解しました。



私の兄と私は本当に犬が欲しかったのですが、これは重い負担だとお父さんに思われました。 それで、犬はお金と努力の投資を必要とする単なる動物ではなく、家族の有用で必要な一員であると父にどうやって納得させることができますか。

私たちは、犬の外観が私たちの家族を幸せにする方法と、彼女の後に餌を与え、歩き、掃除する責任を分かち合う方法の詳細な正当性を書きました。 私たちはスケジュールを提案し、獣医のサービスのためにどのようにお金を稼ぐつもりなのかを考え出しました。 ご覧のとおり、引数は機能しました。 私たちは素晴らしいパグを手に入れました、マギー、彼女は家族の一員になりました。

ドキュメンテーションの「解体」に取り組むリーダーシップを主張するためには、時間とお金の無駄に値するため、これはすでに良いドキュメンテーションへの道の半分です。

結局のところ、これを管理者に納得させることができない場合、変更は必要ないかもしれません。 良い議論は、将来の変更の草案を書くことです。

私たちはリーダーのためのプロジェクトを書いています

プロジェクトを作成するときは、自分が聴衆ではないことに注意してください。 これは次のようなマーケティング文書です。「この作業は重要です。そのためです。 これが私が問題を解決する方法であり、これは会社にそのような利益をもたらします。」

ドキュメンテーション再構築プロジェクトを作成するプロセス自体は、実際の観点から問題をよりよく理解し、遭遇した問題、コンテンツの欠如、未整理の文書、古い情報などを理解するのに役立ちます。

先ほど言ったように、Joyentのドキュメントには多くの問題がありました。 しかし、ドキュメントが形になっていないことを知っていたからといって、クライアントの緊急のニーズを無視できるわけではありません。 計画を立てている間にチケットに答えるのをやめる余裕がなかったので、新しいものを書いて古い文書を改善しなければなりませんでした。 止める機会がありませんでした。

しかし、経営陣を納得させるためにプロジェクトに取り組んで、その後、ドキュメントの戦略的な問題を修正して、将来的には少なくなるようにしました。

変更が必要であることをマネージャーに納得させられない場合、ドキュメントの内容を変更することはできません。

私のプロジェクトを見てみましょう。これは、ドキュメントを「解体」するという提案に対して「はい」という答えを得るのに役立ちました。



まず、成功するプロジェクトはすべて紹介から始まります。 あなたは正しく尋ねます、なぜこれが重要なのですか？ 人々が最初のページでさえマスターしない場合、最初の行から説​​得しない場合、次に提案する議論がどれほどクールであっても関係ありません。 まず、なぜこれが問題なのか、なぜ存在するのかを伝える必要があります。 次のページで読者が期待する内容について読者を準備します。

プロジェクトの最初のバージョンで、Joyentには長い技術的負債があり、ドキュメンテーションをやり直す時が来たという事実を指摘しました。そして今、私たちはこの利点を享受しています。 これは、ドキュメントのある9つの異なるサイトで予想されていました。

議論を補強するために、私は会社の目標について話し始めました。たとえば、オタク向けのニッチな会社ではなく、クラウドプロバイダー市場でナンバーワンになることです。 しかし、マーケティング資料に「私たちは最高です」と書くだけでは、この目標を実現するのに十分ではありません。市場に当社製品の使用方法を伝える必要があります。 誰もこれを知らないなら、あなたがどんなにクールな製品をやっていても。

あなたの会社の目標を考えてください。 あなたが文書を改善するという事実として、それは会社の利益に影響します。

最初に、コンテンツ監査を実施しました。 すべてのドキュメントリポジトリをリストしました。それらに格納されているもの、使用されているCMS、各サイトの主な対象者、ドキュメントを書く人。 次に、どのサイトを残し、どこから情報を転送し、どのサイトを完全に破壊するかを推奨しました。



テクニカルライターの最優先事項は聴衆です。 私たちが行うすべて-私たちは自分自身のためではなく、他の人々のために行います。 幸運にも、オーディエンスをセグメント化する製品またはマーケティングチームがいて、それを保持しているなら、そのようなチームはありませんでした。

私自身、目標別に観客を4つのグループに分けました。

• まず、これらはビジネスオーナーであり、製品の取得に興味がある人は、製品の機能、作業の一般原則、製品の使用を開始する方法を理解したいと考えています。
• 2番目のカテゴリは研究者です 。彼らはすでに製品に精通していますが、高度な機能について学びたいと思っています。
• 第三に、これらは問題を解決したい人々であり 、彼らはパニックでドキュメントに来ました、彼らは問題を抱えており、彼らはすぐにそれを解決したいです。
• 最後に、4番目のカテゴリーは探偵です。製品が特定の機能を実行できるかどうかに関心があるのは、製品マネージャーまたはエンジニアです。

視聴者をこれらのグループに分けることで、期待に応えるコンテンツを作成するために、彼らの目標をよりよく理解し始めました。



ウェブサイトの多様性は私たちの優先課題でした。そのため、一番の目標はコンテンツを統合することでした。再編成する必要がありました。 そして、これは、最初は何が「良い」、何が「悪い」か、何を保存すべきか、何を保存すべきではないかを理解することを意味します。

2番目の目標は、読者がどのような種類の文書を読んでいるかを明確に理解できるように、さまざまな種類のコンテンツ （たとえば、段階的な指示、FAQ、レビュー）に接続されたテンプレートを設定することです。 これにより、コンテンツの検索性が向上しました。

さらに、たとえば、リクエストから発行まで、わかりやすく有益なドキュメントを作成するプロセスを改善するために、 内部目標が必要でした。 ドキュメントのリクエストを作成するためのガイドラインを作成しました。このドキュメントでは、回答が必要な必須の質問、たとえばこのドキュメントの理由やドキュメントに含める必要のある情報を規定しました。 したがって、次のような質問をすると、この状況を回避することができました。 緊急にドキュメントが必要であることはどういう意味ですか、詳細をお知らせください。」

最後に、ドキュメントの廃止計画がないと、ドキュメントの計画は完了しません。ドキュメントが古くなったり、存在しない製品や機能を説明している場合はどうなりますか？ そのような資料をどのようにアーカイブする予定ですか？ たぶん完全に削除する必要がありますか？



これが「ドキュメントライフサイクルプラン」です。ドキュメントの作成から削除までのすべてのステップを考慮する必要があります。 Joyentにとって、これは、アイデアが生まれた瞬間からテキストが書かれるまで、その出版から更新、アーカイブ、または削除に至るまでを意味していました。 各ステップがログに記録され、コンテンツが永久に失われないこと、古いドキュメントから新しいドキュメントへの警告とリダイレクトが設定されていることのチェックがあります。 ユーザーが古いドキュメントを検索する場合、404は表示されません。



その結果、非常に長いタスクのリストがあります。 製品の範囲に含まれるもの、サイトのアーキテクチャー、コンテンツの種類、サイトがデザインに対してどのように見えるかを再説明する必要がありました。



詳細は開示しませんが、これはいくつかのポイントです。これは、スケジュール、ロードマップ、実装に必要なツール、ドキュメントのやり直しとツールの購入にかかる時間とコストの見積り、さらに多くの追加の質問です。たとえば、オープンソースが必要ですかドキュメント？ もしそうなら、これをどのように実装する予定ですか？

「アレクサンドラとフィリップが犬を欲しがる・・・」のように、長くて詳細なプロジェクトか、小さくてコンパクトなプロジェクトかに関係なく、 あなたのプロジェクトがあなたが計画している明確で理解可能な理由を反映することが重要ですそうする必要があります。問題の解決方法とその所要時間以外ではありません。

プロジェクトに命を吹き込みます

プロジェクトの準備が整ったので、リーダーに感銘を受け、彼はリソースと時間を割り当てました。 計画は素晴らしく、プロジェクトは注意を必要とする製品の特定に役立ちます。 プロジェクトの一部を再利用できます。私のプロジェクトの多くは、将来の作業のテンプレートになりました。



すべてのピースをまとめる時が来ました。 プロジェクトを作成して承認した後の次のステップは、コンテンツ戦略です。 実際、ほとんどの作業はすでに完了しています。

6年前、私は非営利組織のデジタルマーケティングマネージャーとして働いていました。 もちろん、マーケティングと技術コンテンツは異なり、マーケティングの目的は販売することであり、技術コンテンツはタスクを支援、指導、または支援することです。 ただし、マーケティング手法は使用できます。 コンテンツ戦略により、ブランディングの一貫性を実現できます。 ユーザーが製品を使用し、広告資料を読み、ドキュメントを読むと、ブランドの統一感を感じるはずです。



たとえば、以前はdocs.joyent.comのサイドバーはこのように見えました。 率直に言って、私が会社に現れる前にサービスの名前は数回変更されましたが、公開製品であるTriton Compute Serviceが同じ方法で更新されていることを確認することが重要でした。

左側にJoyent Cloud製品のメニュー項目が表示されます。 これは、以前の製品の命名法であるJoyent Public Cloudの「レガシー」です。 Triton imagesセクションに名前を付けて更新しましたが、製品名と一致するようになりました。

会社名にはまだ問題があります。 私たちは常に上司と議論しますが、私はしばしば負けます。 ユーザーは製品にJPCという名前を付け、さらにこの頭字語はコードで使用されます。 この名前を過去に残すことは困難です。 しかし、私たちにとっては、少なくとも資料内の単一の製品名を遵守することができます。

製品の命名について言えば、製品とコンポーネントの命名規則を明確に記述し、一貫性を保つために更新された用語集を作成することが重要です。

Dockerなどの他のブランドについてだけでなく、自分自身について話す方法を標準化するスタイルガイドの一部にすることもできます。 スタイルガイドは、どのトーン、どの文法構造、テキストスタイル、使用する規則について同意するのに役立ちます。 その結果、あなた自身がより良い文章を書き、同僚からより高品質のドラフトを取得できます。

戦略のもう1つの重要な部分は、実際には古い文書や資料を「分解」することです。 さまざまなチームに、彼らのコンテンツが2年以上更新されておらず、削除されるというメッセージを書きました。

しかし、実際には、私は完全に削除せず、単にパブリックアクセスから削除し、貴重なものは何もないと確信するまでアーカイブに送信しました。

興味深い事実：JoyentはSamsungの子会社です。つまり、主要な意思決定者は韓国にいます。

Joyentでドキュメントに2年間取り組んだ後、まったく新しいプロジェクトを開始するように依頼されました。 これは、製品の知識に基づいて慎重に構築したコンテンツ戦略を凍結することを意味しました。 すぐに、ドキュメント付きのサイトの新しいタスク指向バージョンに対して受け取ったプルリクエストの処理を停止しました。

この時点で、廃止されたと思われるほとんどすべてのサイトはまだオンラインでした。 しかし、私は自分の仕事から学び、ゼロから新しいプロジェクトに着手しました。

結論は次のとおりです。状況によっては、すべての作業をパイプに入れる必要がある場合があります。

自分がしていることと個人的なつながりを感じてはなりません。さもないと、自分がしたことをすべて放棄することは困難になります。 あなたにとってそれほど価値のあるものはありません。 学んだ教訓を覚えて、将来のプロジェクトで使用してください。

何が恋しい

私はすべてを残さなければならなかったという事実にもかかわらず、私はまだ私の仕事からいくつかの教訓を学びました。 つまり、私が逃したもの。

最初のレッスンは、 ユーザーテストです。 実際、これは最優先事項であり、ツールの予算と、ユーザーがドキュメントで好むものとそうでないものについて話し合うのに費やす時間も必要です。

また、同じことについて同僚ともっと詳しく話したいです。 最終的に、彼らはドキュメントのユーザーでもあり、彼らの声は重要です。 プロセスにそれらを含めると、ドキュメントを支援する意欲が高まります。

ユーザーテストは非常に重要であることを知っています。定期的な調査の形式であっても、見たい人の気持ちを知ることができます。 このタスクをプッシュする必要がありました。



同様に重要なのは、 エンジニアリングチームに対する共感のアイデアです。 より一般的な戦略とサポートコンテンツに集中しながら、同僚がより良いコンテンツを書くことをどのように促進しますか？

ドキュメントを作成するプロセスに同僚を統合する方法、重要な理由を販売する方法がいくつかあります。 回答のグーグル検索を停止する場合は、これらの回答を内部で作成します。

また、ドキュメンテーションの重要性を信じている同僚でさえ、自分の優先事項があることを忘れないでください。 彼らは忙しい人です。 管理には、独自の目標と目標があります。 彼らは最初に仕事を終え、あなたを助ける必要があります。 親切にサポートしてください。

おそらく、このプロセスの最も難しい部分は、このプロセスが重要であることを専門家とエンジニアに確実に理解させることです。 ドキュメントが会社のエンジニアリング文化の一部である場合はさらに良いです。

ドキュメンテーションは、ライターだけでなく、全員のタスクです。 誰もがユーザーの問題を解決したい場合、製品は改善されています。

ジョイエントにとって多様性を考慮することは重要な瞬間です。韓国には従業員がいるため、彼らの考え方を理解する必要がありました。 情報を見つけて問題を解決する方法は、しばしば私たちのものとは異なりました。

組織の文化はドキュメントに影響します。 実際、テキストを書くことは、私たちがどのように学習するか、そして他の人がどのように学習しているように見えるかに常に依存します。

多様性は重要です。 チームに異なるバックグラウンドを持つ人々がいることで、さまざまな学習モデルをよりよく考慮し、より良いコンテンツを作成できます。 そして、成長の余地はたくさんあります。



この物語の主なアイデアを思い出させてください。 最初に、ドキュメントの処理のためのクールなプロジェクトを作成する方法、次に、このプロジェクトを実装するための最初のステップを実行する方法、そして最後に、プロセスで最初に見逃したものについてですが、そうすべきではありません。 主な調査結果は次のとおりです。

• 計画は成功への鍵です。 これらには、プロジェクトと戦略が含まれます。
• ただし、干渉が原因で計画が意味をなさない場合があります。 結果がすぐに本番に移行することもあれば、作業を半ば終わった後、最初からやり直さなければならないこともあります。
• ドキュメントは、ユーザーとエンジニアの両方にとって重要です。 あなたには重要なスキルがあり、他の人が複雑な概念とプロセスを理解するのを助けます。 あなたと同じようにあなたの仕事も重要です。 たとえあなたがそれを言わなくても

あなたの群れの羊飼いになりましょう。 ユーザーと同僚を必要な答えに導きます。

レポートに役立つ資料：

• Joyentのスタイルガイド 。
• MailChimpの音声およびトーンガイド 。
• マイクロソフトドキュメントプランニング 。

アレクサンドラをツイッター 、 Githubでフォローしたり、彼女の個人的なブログを読んだり、講演後のKnowledgeConf 2019やテクニカルライターの国際コミュニティのブースで4月26日にライブでチャットしたりできます。