世界クラスの技術文書を書くための7つのルール

はじめに

技術文書の作成は難しい問題です。 不十分に書かれた技術文書を読むことは、それを書くよりも難しく、おそらく痛みを伴います。 明確で正確で興味深い技術的な説明を作成するには、多くの作業が必要です。 したがって、関係するすべての関係者の生活を少しでも楽にするために、技術文書を作成する際に従う7つのルールを共有したいと思います。



これらの規則は、私自身の発明ではありません。 むしろ、私は単に10年以上の仕事で多くの才能ある技術的および文学的な編集者とコミュニケーションをとることから生まれた経験からそれらを定式化した。 他の人が私に道を示したので、この問題で私が理解したすべてが形成されました。 感謝の気持ちを十分に表す言葉がありません。



この記事を読んだ後、新しいレベルの技術文書を作成するのに役立ついくつかの新しいツールがあなたの武器庫に現れることを願っています。 また、消費者としての追加要件なしで、記事の最後にボーナスを追加しました。これは、技術的な説明を作成するために使用するプロセスの説明です。



7つのルールは次のとおりです。

1. 退屈殺す
2. 始める前に、自分の仕事をマスターした読者に期待する行動を正確に見つけてください。
3. 整形式の構造に従って書く
4. あいまいな代名詞を避ける
5. 明快さ=イラスト+言葉
6. 概念、概念などを扱うときは、論理的な図と例を使用してください。
7. 変更を恐れないでください

1.退屈なキル

このルールは、明らかに、形式化するのが最も難しく、コンプライアンスの観点から最も重要です。 インターネットの現代世界では、読者の注目を集めるために戦っている多くの力があります。 退屈な標準の説明は機能しません。 どんな状況でも、読者は楽しく有益な情報を求めています。 したがって、テキストが不明瞭または興味のない場合、読者は悪名高い「次へ」ボタンをクリックして、別のWebページまたは別のテレビ番組またはFacebookページに移動します。



読者の関心を喚起するために見つけた最も簡単な方法は、自分自身に興味を持つことです。 私は常に自分が読みたい記事を書くために多大な努力を払っています。 私は自分が書いたものを楽しむよう努めています。 私が退屈なら、読者は退屈するでしょう。 私が混乱すると、読者は混乱します。 問題のトピックを気にしない場合、読者はさらに心配しません。 すべてが非常に簡単です！



私はユーモアが好きなので、文学的技術的な「創造」を面白いものにしようとしていますが、もちろん、明快さを損なうことはありません。 私は読者と話をしようとし、彼に教えようとはしません。 私にとって本当に重要なことについて書いています。 読者の混乱を防ぐため、イラストを広く使用しています。



繰り返しになりますが、私は常に読書プロセスを楽しくしようとしています。 私は常に競争の激しい環境で書いていることを覚えています。 読者を惹きつけようとするコンテンツはたくさんあります。 したがって、ルール1についての私のアドバイスは、あなたのテキストがあなたにとって興味深いものであるなら、読者にとっても興味深いものになるでしょう。

2.始める前に、あなたの仕事をマスターした読者にあなたが期待する行動を正確に確かめてください

技術文書は、その後の読者の行動に完全に結び付けられています。 読者は、読書プロセスが完了した後に何かをする意図があるため、あなたの作品を読むのに時間を費やします。 この「何か」には、 クッキーをチョコレートチップで焼いたり、 原子炉をシャットダウンしたり、 Hadoopクラスターを開発したりすることができます 。 読者はあなたの説明を別のプロセスを実行する手段として使用することを覚えておくことが重要です。 あなたの仕事は、さらに明確に定義された振る舞いの一種の指揮者です。



したがって、読み取りプロセスを完了した後、リーダーに期待するアクションを明確に判断することは非常に役立ちます。 最初から意図を述べてください。 読者に推測させないでください。 「この記事を読んだ後、[あなた自身のバージョンを書く]ことができるようになる」など、あなたの声明は単純で明白かもしれません。 読者が読書後に読者に期待する行動を決定した場合、執筆プロセスは最初から簡単になります。

3.整形式の構造に従って書く

整形式の構造は、ドキュメントが成長するフレームワークです。 何らかの構造を使用せずに技術文書を作成することは、計画なしでニューヨークの地下鉄 （469駅！）をナビゲートしようとすることと同等です。 どこにいても、この「どこでも」はあなたが意図した場所ではないかもしれません。



構造に従って技術文書を書くことは、作業量の増加を意味しません。 それどころか、負荷は軽減されます。 構造を操作することで、どこから来てどこへ行くのかがわかります。



私が常に使用する2つの構造化ルールがあります。



1.サブレベルセクションには、少なくとも1つのポジションが必要です。

2.構造の各レベルには、少なくとも2つの文が必要です。



明確にしたいと思います。 以下のリスト1は、最初のルールに違反する構造の例です。 サブレベルセクションには少なくとも1つの位置が必要です。



リスト1：不正な構造



1.オレンジクランベリータンジェリンスパークリングドリンクの準備



1.1。 発泡性飲料を作るために必要な手順



1.1.1。 成分の準備



1.1.2。 発泡性飲料成分の混合



1.1.3。 バブリードリンク



リスト1のレベル1には、「 1.1。発泡性飲料を作るのに必要な手順 」という単一のサブレベルがあることに注意してください。 このような構造は、最初の規則に違反しています。 サブレベルを正しく形成するには、セクションに少なくとも1つ以上の位置が必要です。 つまり、これは、任意のレベルで少なくとも2つのサブレベルが必要であることを意味します。



以下のリスト2を参照してください。 レベル1には3つのサブレベルがあり、それらの「 発泡性飲料成分の混合」セクションにはアイテムが含まれていることに注意してください。 単一レベルの「発泡性飲料を作るのに必要なステップ」は削除されました。



「 発泡性飲料の調製に必要なステップはどこですか？ 」セクションの質問が発生する可能性があります。



リスト2：2つの文の規則に違反する整形式の構造



1.オレンジクランベリータンジェリンスパークリングドリンクの準備



以下のセクションでは、オレンジ-クランベリー-タンジェリンのスパークリングドリンクを準備するために従う必要のあるプロセスについて説明します。



1.1。 成分の準備



1.2。 発泡性飲料成分の混合



1.3。 バブリードリンク



リスト2は整形式のサブレベルを持つ構造を示していますが、レベル1セクションのコンテンツには1つの文しかありません。 構造セクションのコンテンツに1つの文が存在することは、構造化の2番目のルール、「構造の各レベルに少なくとも2つの文があるはずです 」に違反しています 。



リスト3は同じテキストを示していますが、2つの文の規則を強制するために修正されています。



リスト3：2つの文の規則を実装する整形式の構造



1.発泡性オレンジクランベリータンジェリンドリンクの準備



オレンジクランベリータンジェリンスパークリングドリンクは、暑い夏の日に大きな喜びをすることができます。 飲み物は、人工香料のない天然成分で構成されています。 オレンジ-クランベリー-タンジェリンの発泡性飲料は、おいしいだけでなく、非常に健康的です！



以下のセクションでは、オレンジ-クランベリー-タンジェリンのスパークリングドリンクを準備するために従う必要のあるプロセスについて説明します。



1.1。 成分の準備



1.2。 発泡性飲料成分の混合



1.3。 バブリードリンク



なぜ私は各レベルで正しい構造と少なくとも2つの文を心配しているのですか？ まず、サブレベルのルールを順守することで、自分の仕事の論理的なセグメンテーションを非常に明確にすることができます。 サブレベルのルールに従うことは、私のテキストが理にかなっており、従うのが簡単な共通の線と私の考えを結び付けるという事実にも貢献します。



第二に、2つの文の規則では、魅力的で詳細かつ適切なテキストを書く必要があります。 「単文」に書き込むと、詳細が失われることがよくあります。 そして、私たちが格言を考慮しない場合、「1文」のテキストは最も興味深い読書ではありません。

4.あいまいな代名詞を避ける

代名詞の曖昧な使用は、おそらく技術的な説明を準備する際の混乱の最も一般的な原因です。



リスト4の段落を検討してください。



コードリスト4：あいまいな代名詞を含む段落



Trafalgabersは、Vibitatフレームの基本コンポーネントです。 この記事では、それらの概要と使用方法を示します。



この段落は少し滑comicに見えるかもしれませんが、いくつかの重要なポイントを示しています。 最初に、段落は、読者がとる場所にあなたを配置しようとします。 読者は何が起こっているのかを理解したいのですが、使用されている用語に不慣れです。 また、条件が明確ではないため、読者は無能であり、したがって脆弱であると感じています。 読者は新しい情報を必要としています-彼または彼女はもっと賢くなりたいです。 しかし、読者も少し心配しています。 潜在意識レベルであっても、自分の目の前でさえ、自分自身の無能さを前提とすることは、彼にとって不快なことです。 読者は、提示された資料を理解することに非常に敏感です。 執筆者であるあなたが当たり前のように思っている概念や言葉は、読者にとって完全に異質なものです。 説明が不十分な概念や適切な説明なしで使用されている単語があれば、読者は読むのをやめることができます。



上記の段落に関連して、「このトラファルガボールのことは何ですか？」と尋ねても驚かないでしょう。 そして、Vibitataとは何ですか？ この段落は何についてですか？ trafalgaboryの使用方法について または、振動を使用する方法？ または、両方を使用する方法は？ ある種のナンセンス。 Facebookページに戻りたいです。」



読者があなたの説明を読むときに、あなたが彼に伝えようとしていることを理解するのに時間を費やす場合、情報の流れが混乱するだけでなく、読者は混乱する可能性が高いでしょう。 読者を混乱させると、彼を失いました。 読者の注意を引くことを目的とした世界の他のすべてのものは、あなたの創造よりも彼にとって魅力的です。 「次へ」ボタンをクリックすると、あなたの作品は未読のままになります。



リスト4では、2番目の文の代名詞「they」をあいまいに使用した結果、混乱が生じています。 「彼ら」とは何を指すのか-トラファルハボル、ビビタット、またはその両方？ 読者はトラファルガボールやビビタットが何であるかを知らないことを覚えておいてください。 （下の図1を参照してください。）





図 1.曖昧な代名詞の使用は技術的な説明を混同します



解決策は簡単です。 以下のリスト5を参照してください。 あいまいな代名詞は削除されます。 明瞭さが回復しました。



リスト5：あいまいな代名詞の削除



Trafalgabersは、Vibitatフレームの基本コンポーネントです。 この記事では、Trafalgaborの概要と使用方法について説明します。



ご注意 代名詞の曖昧な使用は、混乱を招く技術的な説明につながります。

5.明快さ=イラスト+言葉

下の写真を見てください。 この写真は何ですか？







少し混乱していても驚かないでしょう。 この写真は本当に不可解です。 個々のコンポーネントはすべて知っていますが、それらがすべて一緒に何を意味するのか明確ではありません。 これがイラストの性質です。 言葉のない絵には文脈がありません。



イラストを見るとき、読者は明確にするために文脈が必要です。 問題のグラフィックスが何であるかを理解しようとして時間や労力を浪費することは、読者には受け入れられません。 イラストの曖昧さを解消する最も簡単な方法は、イラストに碑文を提供することです。



写真を見てください。 2以下。 同じ写真です。 しかし、それが何であるかについては疑いの余地はありません。





図 2.オレンジ、クランベリー、タンジェリンのスパークリングドリンクを作るのに必要な道具と材料



技術的な説明については、すべてのイラストに番号付きの説明ラベルを付けると便利です。



数字のみを含むラベルを配置しないでください。 キャプションには数字と説明的なコメントの両方を使用してください。 また、孤立したイラストを表示させないでください。 孤立した図は、技術的な説明に記載されていますが、本文にはリンクがありません。



説明にイラストを挿入するときは、テキスト内でその番号と「上」、「上」、「下」、「下」などの単語を示して参照するようにしてください。 イラストをテキストにリンクしたり、説明内でイラストを検索したりする際に、読者に時間をかけて作品を読んでもらうことはできません。 テキストに追加する場合は、「図 4「その後、テキスト内のどこかで次のようなことを確認してください」を参照 図 4以下。



注 ：目を引き付ける画像



10年前、私は非常に大きなコンピューターメーカーのユーザーマニュアル（印刷出版物）を書いたグループで働いていました。 すべてのマニュアルは、ユーザビリティに関する正式な定量的調査を受けました。 次に、ユーザーインタラクションのスペシャリストから、人がマニュアルを読むとき、彼の目は最初に画像に注目することを学びました。 その場合にのみ、読者はこの画像の周囲のテキストを見ます。 そのため、このガイドの作成者は、各ページに少なくとも1つの画像が含まれるようにしました。

6.概念、概念などを扱うときは、論理的な図と例を使用し、論理的な図と例を使用する

概念を理解することは困難です。これが、概念が「概念」と呼ばれる理由です。 したがって、 熱力学の第二法則 、コーディング手法のコンポーネント、または完全に機能するソフトウェアプラットフォームなど、一般的な状況について記述する必要がある場合、説明では次のアプローチを使用します：コンセプト-論理図-例 論理的な図やさらなる例に裏付けられずに、概念を紹介しようとはしません。



この規則を適用して、初等代数の概念を説明します。



「平等の関係の推移性」の概念は次のとおりです。



A = BおよびB = Cの場合、A = C;



次に、この概念を説明する論理図を示します（図3を参照）。





図 3.平等関係の推移性は、初等代数の基本原理です。



以下のリスト6は、問題の状況の理解を強化するための特定の例を示しています。



リスト6：等式関係推移性のいくつかの具体例

• 7 = 3 + 4および3 + 4 = 5 + 2の場合、7 = 5 + 2。
• 12 + 5 = 7 + 10および7 + 10 = 6 + 11の場合、12 + 5 = 6 + 11。
• x + y = zおよびz = 2aの場合、x + y = 2a。

したがって、ルールが守られます。 「平等の関係の推移性」の概念を導入し、それを説明的な絵で示し、例でそれを支持しました。



ここで、ソフトウェア開発により近く、理解がやや難しい概念を考えてみましょう。 この概念は、 Maven （自動化されたプロジェクトアセンブリシステム） のプロジェクトオブジェクトモデル（POM =プロジェクトオブジェクトモデル）の継承です 。 以下の例1は、検討中の概念を示し、この概念を説明する論理図を示しています。 最後に、継承状況でのPOMファイルの特定の使用を示す別の図があります。



例1：Maven（自動化されたプロジェクトアセンブリシステム）のプロジェクトオブジェクトモデル（POM）の継承の技術的な説明からの抜粋

POMファイル継承ビュー



POMファイルは、 Mavenプロジェクトを記述し、このプロジェクトで作業するために使用されるXMLファイルです。 一部のMavenプロジェクトが別の親POMファイルから設定を継承するように指定できます。 親POMファイルから設定を継承する機能は、POM継承と呼ばれます。 要素を使用しています

<parent>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

POMファイルで、設定の継承元の親POMファイルを指定します。



図 下の4は、条件付きプロジェクトの階層を示しています。これは、他のROMファイルが共通設定を継承できるROMマスターファイルを指定する例です。





図 4.一般設定の継承が発生するROMマスターファイルを割り当てることができます



図 以下の5は、stooges-web、stooges-api、およびstooges-dal MavenプロジェクトのPOM.xmlファイルの内容を示しています。 各プロジェクトは、アイテムを使用するように構成されています。

 <parent>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

stooges-projectから設定を継承します。





図 5.アイテムの使用

 <parent>
      
      

        
        
        
      

    
        
        
        
      
      

        
        
        
      

    
     

外部ROMファイルから設定を継承するMavenプロジェクトを管理するための

上記の例は、主に図面に基づいて論理的な説明を提供し、問題の概念の特定の使用法を示しています。 興味深く、魅力的で、正確なイラストと例を準備することは難しい作業ですが、努力する価値はあります。 技術的なテキストとコード例の多くのイラストを作成するには、テキスト自体を書くよりも時間がかかりません。 したがって、私は時間通りに仕事を完了するために私の時間を計画しています。



そのため、概念を明確に表すには、テキストにイラストと例を含める必要があります。

7.変更を恐れないでください

最初の試行で優れた技術テキストを書くことはほとんど不可能です。 トピックをマスターし、アプローチを整理し、アイデアを明確かつ正確に提示するためのフォームを見つけるには、多くの時間と労力が必要です。 したがって、すべてが初めて正しくなるという期待に戸惑うことはありません。 作成物の少なくとも3つのバージョンを検討することをお勧めします。 最初のバージョンは、印刷された一連の単語であり、意図を実現する機会を提供します。 2番目のバージョンでは、作業の明快さと正確さがすでに得られています。 次に、テキスト内のすべての事実が検証され、イラストが検証され、構造が論理的に構造化されると、魅力的で独創的な3番目のバージョンを準備できます。



この作品について、トーマス・エジソンの有名な引用を言い換えると、 「技術的な文章を書くことは、文学的創作の10％、処理の90％です！」と言えます。

約束のボーナス

世界レベルの技術文書を作成するための7つのルールがわかったので、技術テキストの準備に使用するプロセスの概要を共有したいと思います。 ここに少しですが、要点です。 私はこのプロセスを「-「 技術文書を作成する7つのステップ 」と呼びます 。 」



1.少なくとも2番目のレベル（可能な場合は3番目のレベル）まで構造を作成します。

2.各概念の構造にイラストを追加します。

3.イラストのキャプションを作成します。

4.構造に従ってテキストを作成し、2つの文の規則を観察し、テキストの構造を調整しています。

5.編集、やり直し。

6.レビュー中のトピックの専門家に結果を送信します（このトピックの専門家は、説明の不正確さや曖昧さを特定できる人です）。

7.再度、レビュアーのレビューに基づいて作品を編集します。



そして、あなたはそれらを持っています：7つのルール、7つのステップ。 誰もが必要ですか？ あなたは私のすべてのトリックを知ったので、自由に前進し、世界をより適切で、魅力的で、明確で、興味深い生活の場にします。 彼はそのような努力に値します。