技術文書を正しく作成する

 10 Mar 2022

ドキュメントが不十分だったために起きた次のような製品の障害を考えてみてください。

  • 緊急の臍帯静脈カテーテルの留置に使用されるメスは、使用方法の文書が不十分だったために、安全上のリスクがあった
  • 心臓補助ポンプは、その使用説明書を更新する必要があり、古くなったためにリコールされた
  • 外科手術パックは、リドカインの投与量に誤ったラベルを付けられた(正しい 0.5% ではなく 1% のラベルが付いていた)

ドキュメントが不十分であったり、またはドキュメントの不具合の理由には、次のうち 1つまたはそれ以上が含まれることがあります。

  • 古いドキュメント ー 設計の繰り返し、改訂、更新が続く間、製品の文書化が停止している
  • 十分に、または全く構造化されていないドキュメント(つまり、ナビゲートが困難な)ドキュメントは、構造やまとまりがなく、アドホックな方法で作成されている
  • 詳細が多すぎる ー 利用者が誰で、どのような情報、指示、警告が必要かについての詳細が欠如している、または全く欠落している

理由が何であれ、不十分なドキュメント、ポイントを外したドキュメント、または古いドキュメントは、製品のリコール、市場での不具合、あるいは費用のかかる公的機関の監査につながる可能性があります。上記のいずれかを最近経験した場合、またはチームやビジネスユニット間でドキュメントの作成を調整する方法を検討している場合、あるいは効果的なドキュメントの作成に技術文書内での変更管理が不可欠であることに気付いた場合は、次の 5つの戦略を検討してください。

  1. ドキュメントスキーマに準拠しながら、製品データをコンテンツとして制御する
  2. スキーマ、スタイル、およびオーサリングツールをビジネスに合わせて拡張する
  3. ダイナミックリンクを使用して最新の製品データへのトレーサビリティを実現する
  4. 製品構成管理と同時に、柔軟なプロセスで変更をコントロールする
  5. 単一のソースから複数のドキュメントレイアウトに出力する

設計プロセスでは、製品データ、それも大量のデータが生成されます。しかし、それはコントロールされ、まとまっている必要があります。スプレッドシートやアドホックなオーサリング環境で保持したり、単に設計者の記憶に残したりすることはできません。製品チームのすべてのメンバーが入力およびアクセスできる正式な製品ライフサイクル管理(PLM)プラットフォームである必要があります。次に、どのデータがキャプチャされるか、コンテンツとしてどのように構造化されるか、データ間の関係、およびデータがどのように表示されるかなど、定義されたスキーマによって構造化する必要があります。その後、データは、複数のユースケース、ドメイン、および分野をサポートするために再利用できます。このような環境では、ドキュメントのコンテンツが検証され、現在の製品データが反映されます。この最初のステップは、正確で効果的なドキュメントを作成するための基礎です。

多くの場合、残念ながら、スキーマはプロバイダーによってユーザーであるあなたに強制されています。彼らはそれを産業用に一般化しましたが、その起源はあなたとは関係のない他の産業が元になっていたかもしれません。会社のスタイルガイドとニーズに準拠するドキュメントが必要です。例えば、あなたは自動車業界向けの部品メーカーではなく、圧縮空気をサブスクリプションで提供するコンプレッサーメーカーかもしれません。自社の独自の構造を定義し、独自のスキーマを作成できるようにする必要があります。また、オーサリングプロセスをある程度コントロールできるようにする必要があります。つまり、自社のユーザー、組織、およびプロセスに対応するようにユーザーインターフェイスを変更する必要があります。ドキュメントタイプを作成するための使いやすいツールと、スキーマとスタイルを編集する機能を備えたPLM製品を探してください。自社の環境の作成者をコントロールするように調整できる拡張可能なユーザーインターフェイスフレームワークを備えたシステムを検討してください。また、必要に応じて、業界標準のスキーマとスタイルを簡単に組み込むことができるシステムを探してください。

ドキュメントが正確で影響力のあるものである場合、読者に提示されるデータとコンテンツは最新であり、現在利用可能な他のデータと適切に関連している必要があります。データがシステム内で単に柔軟に浮遊していたり、他のデータと適切に関連していない場合、データが正しいコンテキストで読者に表示される可能性は低く、誤解を招く可能性があります。ドメインとプロセス間でデジタルスレッドによって接続されたデータが必要です。すぐにナビゲートできる簡単な方法で、データとコンテンツ間のこれらの接続性を視覚化できる必要があります。また、製品の成熟度のさまざまなレベルで接続の一貫性と有効性を保証するシステムが必要です。

設計プロセスは一直線ではありません。多くの迂回、遅延、変更、および改訂があります。これは正常な状態であり、実行可能な製品を生産するために必要なことです。これは、いくつかのドメイン分野から入力があったときに発生します。このすべての変更が PLM プラットフォームのコントロール下にあることが重要です。変更履歴は、デジタルスレッドの一部としてキャプチャされ、ドキュメントに含めるコンテンツとして適切かつ正しく利用可能である必要があります。 ユーザーは変更を認識し、変更にコメントしたり、変更を承認したりできる必要があります。データを変更管理下に置くと、現在の PLM データを反映した正確なドキュメントが得られます。

繰り返しになりますが、あなたの会社とあなたの製品はユニークなはずです。そして、さまざまな対象者に向けてドキュメントを公開します。工場現場の保守作業員と病室のモニタリングシステムを使用している看護師は、同じエンドユーザーという立場でほとんど同じような情報を必要としますが、まったく異なる視点から状況を監視しています。公的機関は、多くの同じようなコンテンツを要求しますが、好みの形式で提示されることを望んでいます。時間とお金を節約するには、単一のソースから複数のドキュメントレイアウトとフォーマットにコンテンツを出力できる必要があります。パッケージングには印刷された PDF が必要ですが、メンテナンス担当者はモバイルデバイスでドキュメントの html ビューを必要としています。同じ情報でも、形式が異なるのです。

唯一 Aras だけが、次のような技術文書ソリューションを提供しています。

  • ユーザー定義スキーマのコンテンツとしてデータをコントロール
  • 特定のビジネスニーズと目標に適合するスキーマとオーサリング環境のカスタマイズが可能
  • 自動的なデジタルスレッドでデータとコンテンツをダイナミックにリンク
  • データの変更をコントロールしながら、ライフサイクル全体でデータの一貫性と正確性を確保
  • 単一のソースから複数のドキュメントレイアウトを出力可能

あなたの文書は、あなたのやり方で。Aras の Technical Document Framework をお役立てください。