技術文書の書き方

#1. 準備 準備フェーズ

#準備フェーズの作業には主に次の点が含まれます:

·ドキュメント要件を明確にする

·ドキュメントの対象読者を明確にする

·ドキュメントの範囲を定義する

ドキュメントを作成する前に、文書要件を明確にする必要があります。なぜこの文書を書きたいのか、この文書を書くことでどのような目的を達成したいのかを理解する必要があります。

文書の対象読者を明確にすることも必要です。視聴者によって内容が異なる可能性があります。たとえば、開発者向けのドキュメントと非開発者/一般ユーザー向けのドキュメントでは、コンテンツの構成が異なります。

ドキュメントの範囲も定義します。このドキュメントでカバーする必要があるコンテンツまたはモジュールと、カバーしないコンテンツを検討して決定します。こうすることで、後から情報を集めるときにある程度の焦点が定まり、書くときに曖昧にならずに済みます。

関連する推奨事項: 「

php 入門チュートリアル 」

2. 研究段階

技術的な文章を書いた経験がある方私の友人も間違いなく同じように感じるでしょう。何かが理解できない場合、それについてドキュメントを書くのはとても苦痛です。

では、なじみのないトピックに遭遇して何も分からなくなったときの苦痛を避けるにはどうすればよいでしょうか?もちろん、私はそれを理解するために最善を尽くしているだけです。

しかし、具体的にはどうすればよいでしょうか?一言で言えば情報収集です。では、どうやって情報を集めればよいのでしょうか？著者は、次の点から始めることができると考えています。

(1) より代表的な類似製品または類似製品の関連ドキュメントを調査し、他の人のドキュメントがどのように作成されているかを確認します。

何も知らないときは、他の人の経験や実践から学ぶのが良い選択です。複数の製品のドキュメントを比較することで、作成するドキュメントの大まかな枠組みを確立できます。

リファレンスはコピーではなく、アイデアを提供するためにのみ使用されることに注意してください。製品が異なれば、ドキュメントの構造計画も異なります。

(2) 最も効果的な方法を使用して、作成中の文書に関連するあらゆる種類の情報を収集します。

収集された情報は、テクニカル ライターによって抜粋および整理された後、公開文書の一部となる可能性があります。

情報を収集するには、インターネット検索、アンケート、インタビュー、実験のほか、電子メールでのディスカッション、レポート、技術記事など、さまざまな方法があります。どの方法を使用するかは詳細な分析が必要であり、文書要件、期限、既存データの豊富さなどの要素に基づいて、必要なデータを迅速かつ正確に収集できる方法を選択する必要があります。

執筆トピックによっては、インターネットで検索してもほとんど助けが得られない場合があります。このようなコンテンツでも、開発者から必要に応じて情報提供を依頼したり、開発ノートや社内システムでのディスカッションを通じて必要な情報を入手したりすることができます。

ソフトウェア製品のドキュメントの場合、技術情報が含まれている場合でも、操作手順を直感的に理解し、ドキュメント作成に関する直接の情報を得るために、テクニカル ライターが自らそれを使用する必要があることがよくあります。

3. 組織文書の構造

データがほぼ収集されたら、この文書の具体的な構造を整理できます。類似製品に関する以前の調査は、こちらで行うことができます。手助け。

一般的な製品使用ガイドの場合、通常はインストールまたは使用の順序で編成されていますが、ガイド以外のその他のドキュメントの場合も、特定の順序またはロジックに従う必要があります。

さらに、文書に図を付ける必要があるかどうか、表を使用する必要があるかどうかも考慮する必要があります。写真を追加する必要がある場合は、他の人の助けが必要なのか、それとも自分で完成させる必要があるのか​​を明確にしてください。より複雑な絵を描くことも時間のかかる作業であり、費やす時間も考慮する必要があります。

詳細なドキュメント構造を作成したら、次の作成ステップに進むことができます。

4. 文書の書き方

最初のいくつかのステップをしっかりと行うことができれば、該当する内容を正確に記入するだけで、文書の作成は非常に簡単になります。ドキュメントスキーマに追加します。このプロセスでは、段落または具体的な手順を記述する必要があります。これは、自分の言語スキルとライティングスキルを振り返る時期です。

一部のテクニカル ライティングの本では、ドキュメントを書くときに文法、言葉遣い、句読点を気にする必要はないと述べており、これらの詳細は改訂段階で改善する必要があると考えられています。

Expand your outline into paragraphs, without worrying about grammar, refinements of language usage, or 
punctuation. 
Writing and revising are different activities; refinements come with revision. - Handbook of Technical 
Writing

これについては私は別の見方をしています。資格のあるテクニカル ライターは優れた言語スキルを備えている必要があり、文法、言葉遣い、句読点などの最も基本的な詳細は、一人で解決する必要がある問題になってはいけません。標準的な文法、きちんとした言葉遣い、正しい句読点を身につけることで、余計な努力も時間もほとんどかからずに文章を書く習慣が身につくはずです。

最初の草稿が大まかで、修正が必要な細かい詳細が多数含まれている場合、レビュー中の作業量と時間コストが確実に増加し、文書プロセスが遅れます。

おそらく、この方法は、分業が細分化され、各人が小さなリンクのみを担当する大企業に採用できるでしょう。ただし、これは、急速に開発を進めており、ドキュメントの機敏な開発を必要とするスタートアップには当てはまりません。

5. 改訂

ドキュメントの最初の草稿を作成した後、通常はさらなる改訂と改善が必要になります。ここでの改訂はレビュー後の修正を指すため、このステップは「レビューと改訂」とも呼ばれます。

では、誰がレビューする必要があるのでしょうか?技術文書には通常、他のパートナーからの 2 種類のレビューが必要です。つまり、次のとおりです。

#技術レビュー: 技術的な観点から、文書内の説明が正しく有効であるかどうかを確認します

·言語レビュー: ドキュメント内の表現が簡潔かつ適切であるかどうかを言語レベルからチェックします。

レビュー担当者からフィードバックを受けた後、テクニカル ライターはタイムリーな判断と修正を行う必要があります。不明な点がある場合は、査読者と話し合う必要があります。変更を加えた後、レビュー担当者に見てもらうように依頼してください。新しい問題が発見された場合は、再度修正する必要があります。このレビューと修正のプロセスは数回繰り返される場合がありますが、これは正常な現象です。

もちろん、テクニカル ライターは、他の人にレビューを依頼する前に、低レベルの間違いを避け、他の人の時間を無駄にしないように自分でレビューすることもできます。

あはは、また問題が来ました~ 通常、記事を書き終えたばかりの人は、自分が書いたものを読むのを非常に嫌がりますが、この時点では、文法ツールやスペル チェック ツールを使用すると役に立ちます。あなたです。

自分は十分に注意していて、サポートしてくれるガジェットは必要ないと感じているのであれば、私はあなたの能力を賞賛しますが、それでもガジェットを使用することをお勧めします。なぜなら、体調が優れないとき、疲れて昼寝をしているとき、そして自分が一体何を書いたのかわからないときもあるかもしれないからです...自分自身と自分のガジェットに厳しくしないでください。

6. 納品ドキュメントの納品

ドキュメントが完成したら、プラットフォーム上に公開することができ、操作は一般的に簡単です。企業が異なれば、ドキュメント発行プラットフォームも異なり、テクニカル ライターが使用する執筆ツールも異なります。

ドキュメントを公開したら、それで終わりというわけではありません。私の実務経験によると、大企業の文書であっても中小企業の文書であっても、公開された文書であっても問題が発生する可能性があります。例: 未発見のテキスト エラー、リンク切れ、最新の製品と一致しなくなった説明と手順など。テクニカル ライターは、ドキュメントをタイムリーに更新するために製品開発を常に把握する必要があります。

以上が技術文書の書き方の詳細内容です。詳細については、PHP 中国語 Web サイトの他の関連記事を参照してください。