TL:DR? いいでしょう...ここに:
テクニカル ライターを雇用したり外注したりする以外に、適切な IT ドキュメントを作成し、そのドキュメントを長期にわたって維持するために、テクニカル ライターが業務で採用している基本的な標準、慣習、慣行などはありますか。
社内の IT 使用と従業員による社外使用の両方を目的としたさまざまなドキュメントを作成する中で、ドキュメントに関しては従業員全員が独自のスタイルを持っていることが明らかになりました。
IT 部門は、品質ドキュメントと管理されたドキュメントから、SOP、WI、および IT 品質ドキュメントに使用されるさまざまなフォームのさまざまなテンプレートを活用してきました。これらのドキュメントは、IT 部門内の日常業務に必ずしも役立つわけではありませんが、従業員や会社の IT HR 問題、コンプライアンスなどに役立ち、通常は適切に記述され、適切に定義されており、少なくとも品質部門のテンプレートとドキュメント標準 (バージョン管理、ECN など) に従っています。
しかし、実際の IT ドキュメントの作成には、まだ真の慣例や標準が欠けています。 ScreenSteps などのサードパーティ ツールを使用する人もいれば、Word を使用して次のような簡単なアウトラインを作成する人もいます。
- 開ける
app- 「世界的熱核戦争の開始」をクリック
- ...
- 利益
社内ITドキュメントは実際はもっと悪い従業員またはコンサルタントが、その時点で自分の記憶を呼び起こすのに十分だと感じたもの、または選択したエディタ (vi、word、excel、powerpoint、napkin、社内 wiki) に基づいて作成します。問題は、従業員が退職したり休暇を取ったりして、基本的な情報さえも探し出すのに大混乱が生じた場合に発生します。 場合によっては、ファイルの日付のみが、データがまだ関連しているかどうかの指標となることがあります。
簡単な概要、実際のスクリーンショット、またはフル HD ビデオでも問題ありませんが、当社には実際の IT テクニカル ライターがいないことから、この分野で不足していると感じざるを得ません。
承認されたテンプレートとともに、ドキュメント用の独自の標準を作成することはできますか? はい、できますが、なぜ車輪の再発明をする必要があるのでしょうか? テクニカル ライターの「ギルド」内にそのような標準と規則がすでに存在する場合は、それらの規則に従う方が、ドキュメントが明確で簡潔、かつプロフェッショナルなものになるためです。
言われないように「Googleで調べる「、私はいくつかの書式設定方法を示したサイトを見てきましたが、この SF Q:IT ドキュメント プラットフォーム執筆を処理するためのプラットフォームやソフトウェアを見つけるのに役立ちますが、業界内に本当に標準があるかどうかについては議論されていません。
では、テクニカル ライターを雇用したり外注したりする以外に、適切な IT ドキュメントを作成し、そのドキュメントを長期にわたって維持するために、テクニカル ライターが業務で採用している基本的な標準、慣習、慣行などはありますか?
答え1
書くことは訓練です。
私はたくさんやってきた、そして私は、ドキュメンテーションを仕事の主要部分とせずに、訓練を受けていない人間が習得できる基礎をできるだけ多く習得しています。時間が経つにつれて、私が作成したドキュメントが実際に読まれるのか、そして、永遠の TL;DR の棚にしまわれるのかがわかりました。これは、実際に何かを書くときの第一のルールです。
聴衆を知る。
社内 IT ドキュメントの対象者は私たち自身です。ではシステム管理者はどうでしょうか? ドキュメント、特に社内ドキュメントを入手するときは、次の点に注目します。
- 位置特定可能
- 簡単な
- ポイントへ
- 目的地まで連れて行ってくれる
システムの背景に関する5段落の説明は無視され、その下のチェックリストが優先されます。急いでいるので、とにかくやらなければならないからです。そして、そこに警告があれば、特定の手順を順番通りに実行しないと、すべてのバックアップが消去されますスキップされたテキスト ブロック内にある場合は、注目を集める書式を設定するか、その部分もチェックリストに含める必要があります。
プロセスドキュメント
このタイプのドキュメントは、何かを実行する方法を説明するものです。ほとんどの場合、一連の手順を書き留めるだけなので、訓練を受けていない人でも作成するのが最も簡単です。私の経験では、優れたプロセス ドキュメントには次の特徴があります。
- チェックリストが含まれています。
- チェックリストは、チェックリストが実行されるタイミングと理由の簡単な概要と同じページにあります。
- チェックリストの下、またはリンクされたページには、チェックリストの背後にある理論と、発生する可能性のあるバリエーションを説明する長いドキュメントがあります。
従うべきチェックリストがあり、必要に応じて少なくとも最初のレベルのトラブルシューティング手順がすでにページ上（または 1 クリックで）表示されている必要があります。
これは、Microsoft KB 記事を見たことがあればおなじみの形式です。概要、修正方法、詳細、影響を受けるシステムなどです。それには理由があります。
トラブルシューティングガイド
これはプロセス ドキュメントよりも複雑です。なぜなら、ドキュメントに決定木をエンコードする必要があるからです。単純なチェックリストではおそらく不十分ですが、他のチェックリストへのリンクを使用する分岐チェックリストであれば、十分に実行可能です。この種のドキュメントには、プロセス ドキュメントと同じルールが適用されます。
- 簡潔に述べ、読者を詳細に圧倒させないでください。
- 意思決定のポイントと、その後のアクションを実行する場所を明確にします。
- 詳細な技術的背景説明は、アーキテクチャ ドキュメントに保存してください。
トラブルシューティング ガイドは、大規模な「Choose Your Own Adventure」ストーリーになることもあれば、システムで発生したすべての問題とその解決方法を箇条書きにした大規模なリストになることもあります。
アーキテクチャドキュメント
作成するのが最も難しいタイプです。これは、複雑なものを理解しようとしている新しい人々だけが参照する参考資料として設計されているためです。
アーキテクチャ ドキュメントは、理由を説明するドキュメントです。このシステムが使用され、他のシステムが使用されない理由、他のシステムとの接続方法、接続がこのように機能する理由について説明します。これは、本番構成がどのようなものかがわかったらすぐに作成し、変更があった場合は更新する必要があるドキュメントです。
形式に関しては、この点については専門家に任せるしかありません。
優れたドキュメントは、テンプレートとフォーマットだけではありません。統一された外観は優れており、読みやすさを向上させますが、他にもいくつかの要素が必要です。
定期的な更新
すでに持っているドキュメントに目を通し、それがまだ適切であることを確認する習慣をつけましょう。バージョン 1.17 のチェックリストはバージョン 1.26 には適さない可能性があります。更新する時期です。UI のわずかな変更でも全体が台無しになる可能性があるため、定型チェックリストは最も更新が必要です。
10分を費やす一週間ドキュメントを確認してクリーンアップが必要なものを特定すると、驚くべき効果が得られます。
アーキテクチャ ドキュメントは、システムに精通した人物によって定期的に確認される必要があります。前述したように、これらのドキュメントはほとんど使用されませんが、実際に必要になったときには非常に役立ちます。3 年前に Windows に移行したときに、キャンパスのプリント サービス クラスターが NetWare とどのように接続されていたかを説明するドキュメントは不要です。
発見可能
これは、正しく行うのが最も難しいです。なぜなら、それはどこドキュメントを保存しています。
ServerFault に質問を持って来た人に私たちが伝えていることは何ですか?
すでに何を試しましたか?
すぐに
Google のトップヒットで問題が解決します。試してみるといいかもしれません。
私たちはドキュメントを探すのであって、本棚に行くのではありません。ドキュメント リポジトリは Google と同じように検索可能である必要があります。そうでないと、代わりに Google にアクセスすることになります。
中央 Napkin リポジトリは、少なくともオンライン インデックスがない場合 (そして、そうならないでしょう)、ドキュメントを保存するのに適していません。シンプルな wiki の方が適しています。ほとんどの wiki には、少なくとも基本的なテキスト検索機能が含まれています。より優れたシステムは、全文検索に加えてタグ検索も可能で、対象領域に検索を絞り込めるシステムです。
タグをサポートするドキュメントリポジトリを使用している場合は、タグを標準化する理由を知るには、ServerFaultのタグリストを一度見てみてください。ユーザーは、ヴイエムウェア探しているものを見つけるためだけに。これには時々タグの再設定作業が必要になります。