Skip to main content
Contributor's Guide
日本語は機械翻訳による参考訳です。内容に矛盾や不一致があった場合には、英語の内容が優先されます。

ネットアップのドキュメントのスタイルガイド

共同作成者

私たちのスタイルは会話型で共感的ですが、プロ意識を維持し、その点に到達しています。ネットアップのドキュメントのコンテンツを作成する際は、次のガイドラインに従ってください。

書き込みの変換

プロの同僚に何かを説明しているときは、話すように書いてください。会話の中で文章を書くと、聞き手とつながりやすくなります。

形式が多すぎます カジュアルすぎます 私たちのスタイル

BlueXPの階層化で問題が発生した場合は、クラスタダッシュボードで健全性ステータスを確認してエラーが発生した理由を確認できます。ヘルスは、 ONTAP システムとサービスコネクタのステータスを表します。

失敗が起こるのは楽しいことではありません。クラスタダッシュボードで何が起こったのか、何が影響を受けるのかを確認してください。

BlueXP階層化サービスで障害が発生すると、クラスタダッシュボードに「失敗」の健常性ステータスが表示されます。ステータスを表示して、障害に関する情報を確認します。

ストレージをプロビジョニングする前に、BlueXPからONTAPクラスタを検出する必要があります。検出が完了したら、作業環境を開いてストレージをプロビジョニングする必要があります。

最初にBlueXPからONTAPクラスタを検出し、作業環境を開いてストレージのプロビジョニングを開始するだけです。簡単!

BlueXPからONTAPクラスタを検出したら、作業環境を開いてストレージをプロビジョニングします。

セットアップウィザードが起動したら、ウィザードの指示に従ってノードをセットアップし、クラスタに追加します。以下に、ウィザードでの手順を示します。

セットアップウィザードが表示されます。このウィザードで、ノードを設定してクラスタに追加する簡単な手順を説明します。

セットアップウィザードの手順に従ってノードをセットアップし、クラスタに追加します。

新しいシステムのインストールとセットアップには、複数のコンテンツ形式から選択できます。各フォーマットタイプは、詳細な手順を提供します。学習方法に最も近い形式を選択してください。

システムをどのようにセットアップしてインストールしますか?複数のコンテンツ形式での手順を説明しますが、学習方法は知っているものだけです。

システムの設置とセットアップをガイドするコンテンツフォーマットタイプを選択します。

収縮を使用する

収縮はAを強化します。 会話のトーンそして、多くの収縮は理解しやすく翻訳しやすいです。

展開して詳細を確認
  • 次のような収縮を使用します。これらの収縮は理解しやすく翻訳も簡単です。

    そうじゃない

    お前は…​

    ありません

    ネットアップは

    はいませんでした

    それはある

    ありませんでした

    それでは

    分かりませんでした

    (将来時制が必要な場合)

    ありません

    できない(将来の緊張が必要な場合)

    しないでください

    将来の緊張感が必要な場合は、

  • これらのような逆収縮は、理解して翻訳するのが難しいため使用しないでください。

    もしそうなら

    すべきだった

    そんなことはしない

    すべきではなかった

    可能性があった

    できませんでした

簡単に記入してください

複雑で大きな言葉は避けてください。シンプルに管理あなたは専門の同僚に何かを説明していて、あなたの語彙を誇示していません。

これではなく:「NetApp Cloud Centralアカウントとユーザの関連付けを解除してください。」

手順:「NetApp Cloud Centralアカウントからユーザを削除してください。」

最小限の情報を書き込みます

短い簡潔な文章で、コンテンツの読み取りやスキャンが簡単になります。時 々 長い文を使っても構いませんが、短い文で続けても構いません。いいですね。

ではなく:「AWSのCloud Volumes ONTAPシステムと他のネットワークのONTAPシステムの間でデータをレプリケートするには、Amazon VPCと他のネットワーク(Azure VNetや企業ネットワークなど)の間にVPN接続が必要です。」

これを行う:「ネットワーク間のデータレプリケーションには、VPNを介した接続が必要です。たとえば、Amazon VPCと企業ネットワークの間、AWSとAzureの間などです。」

次のことを自問してください。

  • この時点で、ユーザーはこのコンテンツを必要としていますか?

  • ユーザインターフェイスはすでに十分にユーザを誘導していますか。そうでない場合、簡潔に追加できる追加ガイダンスは何ですか?

  • あまり形式的でない、またはあまりにカジュアルではなく、より少ない言葉でコンテンツを表示できますか?

  • 長い文章を短くしたり、単純化したり、 2 つ以上の文章に分割することはできますか?

  • リストを使用して、コンテンツをスキャン可能にできますか。

  • グラフィックを使用してテキストブロックを補強または置換できますか。

積極的に書く

受動的な声を避けることは技術的な執筆のための標準的な規則であるが、会話的な音を鳴らすためにアクティブな声を使用することは特に重要である。

アクティブボイス

文の主題が動詞の行動を実行するようにアクティブな声を使用してください。これは通常、動詞が文の主題に従うことを意味します。アクティブな音声で、明瞭かつ鮮明に表現できます。パッシブボイスを使用する特定の理由がない限り、アクティブボイスを使用し、ユーザを「あなた」として直接アドレス指定します。

ここでは、優れたアクティブな音声ライティングの例をいくつか示します。次のように書きます。

  • 最初のクラスタを導入する前に、必要な権限を指定してください。

  • システムを不適切にシャットダウンすると、インターフェイスに警告メッセージが表示されます。

  • ネットアップは契約を受領しました。

パッシブ音声

受動的な声では、行動の doer は不明である:

  • システムが正しくシャットダウンされていない場合は、警告メッセージが表示されます。

  • ネットアップは契約を獲得しました。

次の場合にパッシブボイスを使用:

  • 誰が、何がアクションを実行したのかはわかりません。

  • アクションの結果に対するユーザーの責任を回避したい場合。

  • 前提条件の情報など、周囲に書くことはできません。

必須の気分

手順、指示、要求、およびユーザアクションのリストの見出しには、必須のムードを使用します。

  • [Working Environments]ページで、[Discover]をクリックし、ONTAP Cluster]を選択します。

  • カムハンドルを回転させて、電源装置と同一面になるようにします。

パッシブボイスの代わりに必ず音声を使用することを検討してください。

ではなく:「最初のクラスタを導入する前に、必要な権限を指定する必要があります。」

この手順:「最初のクラスタを導入する前に、必要な権限を指定してください。」

概念的な情報とリファレンス情報に手順を組み込む場合は、 imperative voice を使用しないでください。

その他の動詞の規則については、次を参照してください。

整合性のあるコンテンツの書き込み

「プロの同僚に何かを説明しているときは、話すように書く」ということは、誰にとっても何か違うことを意味します。私たちのプロフェッショナルでありながら会話スタイルは、私たちをユーザーと結び付け、複数の投稿者間で小さな矛盾が発生する頻度を高めます。

  • コンテンツを明確にして使いやすくすることに重点を置いています。すべてのコンテンツが明確で使いやすい場合は、小さな矛盾は問題になりません。

  • あなたが書いているページ内で一貫性を保ちなさい。

  • のガイドラインに必ず従ってください グローバルユーザー向けに作成します

包括的な言語を使用します

ネットアップは、製品ドキュメントに記載されている言語を差別化して排他的に使用することはできないと考えてい私たちが使用する言葉は、お客様との良好な関係を築くことと、お客様を離れさせることの違いを生み出すことができます。特に、言葉を書くと、意図よりもインパクトが重要になります。

ネットアップ製品のコンテンツを作成する際には、デグレード、人種差別、表現力の低下と解釈される言語は使用しないでください。その代わりに、ドキュメントを使用する必要があるすべてのユーザーにアクセスして歓迎される言語を使用してください。たとえば、「マスター / スレーブ」ではなく「プライマリ / セカンダリ」と指定します。

最初にその人を指し、次に障害を指す場合は、人を第一言語として使用します。

彼、彼、彼、彼女、彼女を使用しないでください。 または一般的な参照で彼女のもの。代わりに:

  • 2人目の人(あなた)を使用するように文を書き直します。

  • 文を複数の名詞と代名詞に書き換えます。

  • 代名詞の代わりに「」または「A」を使用します(例:「ドキュメント」)。

  • ユーザーの役割(リーダー、従業員、顧客、クライアントなど)を参照します。

  • 「個人」または「個人」という用語を使用してください。

包括的または排他的と見なされる単語やフレーズの例

包括的な例 限定的な例

プライマリ/セカンダリ

マスター/スレーブ

許可リスト

ホワイトリスト

ブロックリスト

ブラックリスト

停止します

殺す

応答を停止

ハング

終了またはキャンセル

中止

人時

マンアワー

開発者は開発環境内のサーバーにアクセスする必要がありますが、Azure内のサーバーにアクセスする必要はありません。

開発者は開発環境内のサーバーにアクセスする必要がありますが、Azure内のサーバーにアクセスする必要はありません。

目が見えない人

視力障害

視力の低い人

視力障害

その点に到達します

各ページは、ユーザーにとって最も重要なものから始める必要があります。私たちは、ユーザーが何をしようとしているのかを調べ、その目標を達成するための支援に焦点を当てる必要があります。また、スキャン能力を向上させるために、文の先頭にキーワードを追加する必要があります。

次の一般的な文のガイドラインに従ってください。

  • 正確に言うと

  • フィラーの言葉は避けてください。

  • 短くしてください。

  • 書式設定されたテキストまたは箇条書きリストを使用して、キーポイントを強調表示します。

ポイントに到達する例

良い例 悪い例

厳しいセキュリティポリシーが適用されている場合は、転送中データの暗号化を使用して、異なるネットワークにあるNFSサーバ間でデータを同期します。

Cloud Syncでは、転送中データ暗号化を使用して、あるNFSサーバから別のNFSサーバにデータを同期できます。データを暗号化すると、ネットワーク経由でデータを転送するための厳格なセキュリティポリシーがある場合に役立ちます。

頻繁に使用するスタイル、フォーマット、およびページレイアウトを含むドキュメントテンプレートを作成することで、時間を節約できます。その後、新しいドキュメントを作成するたびにテンプレートを使用します。

テンプレートは、新しいドキュメントを作成するための出発点となります。テンプレートには、頻繁に使用するスタイル、フォーマット、およびページレイアウトを含めることができます。ドキュメントに同じページレイアウトとスタイルを使用することが多い場合は、テンプレートの作成を検討してください。

Astra Controlには3つの運用モードが用意されており、ユーザに割り当ててAstra Controlとクラウド環境間のアクセスを慎重に制御できます。

Astra Controlでは、AWSアカウントのユーザに3つの運用モードのいずれかを割り当てることができます。モードを使用すると、ITポリシーに基づいてAstra Controlとクラウド環境間のアクセスを慎重に制御できます。

多くのビジュアル要素を使用します

ほとんどの人は視覚的な学習者である。ビデオ、図、スクリーンショットを使用して、学習を改善し、テキストのブロックを分割し、タスクの指示のどこにいるかをユーザーに視覚的に示すことができます。

  • 「次の図は、背面パネルのAC電源装置LEDを示しています。」

  • 図の位置を「following」または「preceding」、「not」「above」または「below」と参照してください。

  • 埋め込まれたビジュアルに代替テキストを使用します。

  • ビジュアルがステップに関連している場合は、ステップの直後にビジュアルを含め、ステップ番号に合わせてインデントします。

スクリーンショットのベストプラクティス:

  • 1つのタスクに含めるスクリーンショットは5つまでです。

  • スクリーンショットにテキストを含めないでください。代わりに番号付きコールアウトを使用します。

  • 含めることを選択したスクリーンショットを慎重に使用してください。スクリーンショットはすぐに古くなる可能性があります。

ビデオまたはアニメーションのベストプラクティス:

  • ビデオの長さは5分未満である必要があります。

スキャン可能なコンテンツを作成します

セクション見出しの下にテキストを整理したり、リストや表を使用して、読者がコンテンツをすばやく見つけられるように支援します。見出し、文、段落は短くて読みやすいものにする必要があります。最も重要な情報を最初に提供する必要があります。

ユーザの目標達成を支援するワークフローを作成する

ユーザーはコンテンツを読み、特定の目標を達成します。ユーザーは、必要なコンテンツを検索し、目標を達成し、家族に向けて家に帰りたいと考えています。私たちの仕事は、製品や機能を文書化することではありません。私たちの仕事は、ユーザーの目標を文書化することです。ワークフローは、ユーザの目標達成を支援する最も直接的な方法です。

ワークフローとは、ユーザの目標を達成する方法を説明する一連のステップまたはサブタスクです。ワークフローの範囲は完全な目標です。

たとえば、ボリューム自体での作成は完全な目標ではないため、ボリュームの作成手順はワークフローにはなりません。ESX サーバでストレージを使用できるようにする手順は、ワークフローになります。この手順には、ボリュームの作成だけでなく、ボリュームのエクスポート、必要な権限の設定、ネットワークインターフェイスの作成などが含まれます。

ワークフローは、お客様のユースケースに基づいています。ワークフローは、目標を達成するための最良の方法を 1 つだけ示しています。

ユーザーの目標に基づいてコンテンツを整理する

ユーザーが達成しようとしている目標に基づいてコンテンツを整理することで、ユーザーが情報をすばやく見つけるのを支援します。この標準環境では、ドキュメントサイトの目次(ナビゲーション)と、サイトに表示される個 々 のページを表示します。

次のようにコンテンツを整理します。

左側ナビゲーションの最初のエントリ(高レベル)

ユーザーが達成しようとしている目標に沿ってコンテンツを整理します。たとえば、サイトのナビゲーションの最初のエントリは「Get started」または「Protect data」です。

ドキュメントサイトのナビゲーションの2番目のレベルのエントリ(中規模)

目標を構成する幅広いタスクを中心にコンテンツを整理する。

たとえば、「Get started」セクションには次のページが含まれます。

  • 設置を準備

  • <product name>のインストールとセットアップ

  • ライセンスをセットアップする

  • 次は何ができるか

個々のページ(詳細レベル)

各ページで、広範なタスクを構成する個 々 のタスクを中心にコンテンツを整理します。たとえば、インストールの準備やディザスタリカバリの設定に必要なコンテンツなどです。

1つのページには、1つのタスクまたは複数のタスクを記述できます。複数のタスクがある場合は、ページの別 々 のセクションで説明する必要があります。各セクションは、幅広いタスクの1つの学習または実行面に焦点を当てる必要があります。これには、タスクを完了するために必要な概念や参照ベースの情報が含まれる場合があります。

グローバルユーザー向けに作成します

私たちのドキュメントは、主な言語が英語ではない多くのユーザーに読まれています。当社は、Neural Machine Translationツールや人間による翻訳を使用して、コンテンツを他の言語に翻訳しています。世界中のユーザーをサポートするために、読みやすく翻訳しやすいコンテンツを作成しています。

以下のガイドラインに従って、グローバルユーザー向けに記事を作成してください。

  • 短い簡潔な文を書く。

  • 標準の文法と句読点を使用します。

  • 1 つの意味に 1 つの単語を使用し、 1 つの単語に 1 つの意味を使用します。

  • 共通の収縮を使用します。

  • グラフィックを使用してテキストを明確にするか、置換します。

  • グラフィックにテキストを埋め込むことは避けてください。

  • 1 つの文字列に 3 つ以上の名詞を含めないでください。

  • 不明な許可を受けないようにします。

  • 専門用語、口語、および比喩は避けてください。

  • テクニカル以外の例は避けてください。

  • ハードリターンと間隔を使用しないでください。

  • ユーモアや皮肉を使わないでください。

  • 差別的な内容を使用しないでください。

  • 特定のペルソナのために執筆している場合を除き、性別に偏った言語を使用しないでください。

A~Z のガイドラインです

略語と略語

よく知られた頭字語や略語を使用して親しみやすくしますが、明瞭さや検索性に悪影響を及ぼす可能性のあるあいまいな頭字語や略語は使用しないでください。頭字語および略語のその他の表記法については、を参照してください "『 Microsoft Writing Style Guide 』"

アクティブ音声(パッシブ音声との比較)

を参照してください 積極的に書く

モニター

警告は、正しく使用されたときに強力なツールです。重要な情報に注意を向けたり、役立つヒントを提供したり、潜在的な危険性についてユーザーに警告したりすることができます。過剰に使用すると、影響を失い、ユーザーの疲労につながる可能性があります。ここでは、警告の効果的な使用を確実にするためのいくつかのガイドラインを示します。

次のラベルを使用して、メインコンテンツフローから警告を分離します。

  • メモ「メモ」を使用して、テキストの残りの部分から際立たなければならない重要な情報を強調します。ただし、ユーザーがタスクを理解したり完了したりするために不可欠ではない「知っておくべき」情報にはメモを使用しないでください。ノートの目的は、他の方法では見落とされるかもしれない重要なポイントに読者の注意を引くことです。

  • ヒントヒントは、デフォルトでベストプラクティス情報を文書化することをポリシーとしているため、使用する場合は慎重に行う必要があります。必要に応じて、ヒントを使用して、ユーザーが製品を使用したり、ステップやタスクをより簡単かつ効率的に完了するのに役立つベストプラクティス情報を強調します。ヒントは、ユーザーのエクスペリエンスを向上させるための有用なアドバイスやショートカットを提供する必要があります。

  • 注意人身傷害や装置の損傷など、望ましくない結果につながる可能性のある条件や操作については、ユーザーに注意して警告してください。危害や混乱を防止するためにユーザーが避けるべき潜在的な危険に注意を喚起するためには、注意を払う必要があります。

  • ベストプラクティスベストプラクティスを使用して、タスクを完了するためまたは製品を使用するための最適な方法を強調します。これらは単なる提案ではなく、専門家や業界標準によって検証された戦略です。

    • *ベストプラクティスは何ですか?*これは、明確な利点を提供し、信頼できるソースによって裏付けられた、実行可能なタスク固有の戦略です。

    • *いつ使用できますか?*すべてのコンテンツタイプとすべての対象者にベストプラクティスを適用できます。ヒントのように、それらの重要性を維持するために控えめに使用してください。

    • *どのようにフォーマットすればよいですか?*一貫した使いやすい形式でベストプラクティスを提示します。コンテキストに応じて、箇条書き、番号付きリスト、段落などを指定できます。

その他のガイドライン
  • サポートされている警告のみを使用します。その他の形式はサポートされていません。

  • 警告を過度に使用しないでください。過度に使用すると、ユーザーはこれらの重要なセクションをスキップする可能性があります。これは、それらがドキュメントの「ジャンクドロワー」と見なされるためです。

  • 経験則として、警告の数は1ページあたり最大3つに制限してください。

  • 警告の中で明確で簡潔な情報を提供します。メッセージは簡潔で要点を示し、ユーザーが提供された情報の重要性をすばやく理解できるようにする必要があります。

  • AsciiDocの警告は表に記載しないでください。コンテンツをメモ、ヒント、または注意として識別する必要がある場合は、メモ:、ヒント:、 または注意:テキストへのインラインリードインとして。

導入後(「1回」とは対照的)

  • 「後」を使用して、「電源を入れた後にコンピュータの電源を入れます」という時系列を示します。

  • 「1回」は「1回」を意味する場合にのみ使用してください。

また

  • 「追加」を意味するには、「も」を使用します。

  • 「代替」という意味で「also」を使用しないでください。

および / または

用語がある場合は、より正確な用語を選択します。どちらの用語ももう一方の用語よりも正確でない場合は、「AND / OR」を使用します。

として

「理由」という意味で「as」を使用しないでください。

を使用する(「using」または「with」とは対照的)

  • を使用しているエンティティが主体である場合は'を使用して使用しますコンポーネントメニューを使用して'リポジトリに新しいコンポーネントを追加できます

  • You can begin a sentence with either "using" or "with" which are sometimes acceptable with product names:"Using SnapDriveを使用すると、Windows環境で仮想ディスクとSnapshotコピーを管理できます。"

CAN(対「might」、「May」、「should」、「must」)

  • 「CAN」を使用して機能を示します。「この手順中はいつでも変更をコミットできます。」

  • 「might」を使用して、「複数のプログラムをダウンロードすると処理時間に影響する可能性があります」という可能性を示します。

  • 「may」は使用しないでください。機能または権限のいずれかを意味する可能性があるため、あいまいです。

  • 推奨されるがオプションのアクションを指定するには、「should」を使用します。代わりに、「We recommend」などの別のフレーズを使用することを検討してください。

  • 「must」の使用は避けてください。 パッシブ。命令的な音声を使用して、思考を命令として再調整することを検討してください。「must」を使用する場合は、必要なアクションまたは条件を示すために使用します。

資本金

ほとんどすべての場合、文スタイルの大文字と小文字を使用します。大文字のみ:

  • 表の見出しを含む、センテンスと見出しの最初の単語

  • 文の断片を含むリスト項目の最初の単語

  • 適切な名詞

  • ドキュメントのタイトルと字幕( 5 文字以上の主な単語や前の位置をすべて大文字にする)

  • UI 要素。ただし、インターフェイス内で大文字になっている場合に限ります。それ以外の場合は小文字を使用します。

注意事項

を参照してください モニター

収縮

使用 収縮 対話的に書くことの一部として。

確実にする(「confirm」または「verify」ではなく)

  • 「確実にする」を意味するには、「確実にする」を使用します。 必要に応じて「that」を含めます。「イラストの周囲に十分な空白があることを確認してください。」

  • Never use "ensure" to imply a promise or guarantee:"Cloud Managerを使用して、ONTAPクラスタでNFSボリュームとCIFSボリュームをプロビジョニングできるようにします。"

  • すでに存在するものやすでに発生したものを再確認する必要がある場合は、「confirm」または「verify」を使用します。「Verify that NFS is set up on the cluster」

グラフィックス

を参照してください 多くのビジュアル要素を使用します

文法

特に明記されていない限り、文法、句読点、および次の表記法に従ってください。

そうでない場合は

「そうでない場合」を単独で使用して前の文を参照しないでください。

  • ではなく:「コンピュータの電源がオフになっている必要があります。そうでない場合は、オフにしてください。"

  • これを実行 : " コンピュータがオフになっていることを確認してください。 "

if(「whether」または「when」との比較)

  • 「If」を使用して条件を指定します。たとえば、「If this, then that」のように指定します。

  • 明示的または黙示的な条件がある場合は、「whether」を使用します。翻訳を容易にするためには、「どうか」を単独で置き換えるのが最適です。

  • 時間の経過を示すには、「when」を使用します。

命令的な音声

を参照してください 積極的に書く

今後の機能またはリリース

機能や機能が「現在サポートされていない」と言う以外に、今後の製品リリースや機能のタイミングや内容を言及しないでください。

技術情報アーティクル:「 Referring to

該当する場合は、 KB (ネットアップナレッジベース)記事を参照してください。リソースページおよび GitHub コンテンツの場合は、リンクを実行中のテキストに配置します。

リスト

情報のリストは、通常、テキストのブロックよりもスキャンして吸収する方が簡単です。複雑な情報をリスト形式で表示することで、単純化する方法を検討します。以下に一般的なガイドラインをいくつか示しますが、あなたの判断を使用してください。

  • リストの理由が明確であることを確認します。完全な文、コロン付きの文、または見出しでリストを紹介します。

  • リスト内でリストを使用する場合は、構造の深さを最大2レベルに制限して、明瞭さと読みやすさを維持します。より多くのレベルが必要な場合は、ユーザーがナビゲートして理解しやすくするために、コンテンツを再編成することを検討してください。

  • ネストされたリストも含め、すべてのリストには2~7個のエントリが必要です。一般に、各エントリの情報が短いほど、リストをスキャン可能なまま追加できるエントリが増えます。リストにネストされたリストを含む複数のエントリがある場合は、セクションまたはブロックタイトルを使用して、全体をより消費可能なチャンクに分割することを検討してください。

  • リストエントリは、できる限りスキャン可能にする必要があります。リストエントリをスキャン可能な状態に保つ方法でテキストのブロックを避けます。

  • リストエントリは大文字で開始する必要があり、リストエントリは文法的に平行である必要があります。たとえば、名詞または動詞を使用して各エントリを開始します。

    • すべてのリストエントリが完全な文の場合は、ピリオドで終了します。

    • すべてのリストエントリが文の断片である場合は、ピリオドで終わらないでください。

  • リストエントリは、アルファベット順や年代順に並べ替える必要があります。

ローカリゼーション

ミニマリズム

を参照してください 最小限の情報を書き込みます

数字

  • 次の例外を除いて、 10 以上のすべての数値にアラビア数字を使用します。

    • 文字列の先頭に数字を使用する場合は、アラビア数字ではなく、単語を使用します。

    • 概算の数値には(数字ではなく)単語を使用します。

  • 10 未満の数字には単語を使用します。

  • 10 未満の数字と 10 を超える数字が混在する文がある場合は、すべての数字にアラビア数字を使用します。

  • その他の番号規則については、を参照してください。 "『 Microsoft Writing Style Guide 』"

多賀主義

ネットアップの製品、およびネットアップ製品とサードパーティ製品との連携について記載します。サードパーティ製品は文書化しません。サードパーティのコンテンツをコピーしてドキュメントに貼り付ける必要はなく、絶対にコピーしないでください。

前提条件

前提条件は、存在する必要がある条件、または現在のタスクを開始する前にユーザが完了しておく必要がある操作を示します。

  • 「前提条件」、「開始する前に」、「開始する前に」などの見出しでコンテンツの性質を識別します。

  • 前提条件の言葉にパッシブな声を使用することが妥当な場合は、次のようにします。

    • "クラスタでNFSまたはCIFSがセットアップされている必要があります。"

    • "Cloud Managerにクラスタを追加するには、クラスタ管理IPアドレスと管理者ユーザアカウントのパスワードが必要です。"

  • 必要に応じて「NFSまたはCIFSがクラスタでセットアップされている必要があります」を明確にします。System ManagerまたはCLIを使用してNFSとCIFSをセットアップできます。"

  • 他の方法で情報を提示することも検討してください。たとえば、現在のタスクの最初のステップとしてコンテンツをリワードするのが適切かどうかを検討します。

    • 前提条件:「最初のクラスタを導入するには、必要な権限が必要です。」

    • 手順:最初のクラスタを導入するために必要な権限を指定します。

以前("before"、"previous"、"previous"、"previous")

  • 可能であれば、「前」を「前」に置き換えます。

  • 「before」を使用できない場合は、「prior」を形容詞として使用して、時間の早い時期に発生した、または重要度の高いものを参照してください。

  • 指定されていない時間前に発生したことを示すには、「previous」を使用します。

  • 直前に発生したことを示すには、「preceding」を使用します。

句読点

シンプルに管理一般に、文章に含まれる句読点が多いほど、理解するために必要な脳細胞が増えます。

  • 3つ以上の項目の物語リストでは、接続詞(「and」または「or」)の前にシリアルコンマ(オックスフォード・コンマ)を使用します。

  • セミコロンとコロンの使用を制限します。

  • 特に明記されていない限り、文法、句読点、および次の表記法に従ってください。

以来

時間の経過を示すには、「Since」を使用します。「Since」を「because」の意味に使用しないでください。

スペルチェック

特に明記されていない限り、文法、句読点、および次の表記法に従ってください。

それ(「どちら」または「誰」との対比)

  • 文が意味を成すために必要な節を導入するには、"that"(末尾のコンマなし)を使用します。

  • 英語で文が明瞭であっても"that"を使用してください。"verify that the computer is off(コンピュータの電源がオフになっていることを確認してください)"

  • 「which」(末尾にカンマを含む)を使用して、補足情報を追加しますが、文が意味を成すために必要ではない句を導入します。

  • 「Who」を使用して、Peopleを参照する句を紹介します。

商標

当社の技術コンテンツのほとんどに商標記号は含まれていません。これは、テンプレートの法的記述で十分であるためです。ただし、を使用する場合は、すべての使用規則に従ってください "ネットアップの商標"

  • 商標用語は、形容詞としてのみ使用し、名詞、動詞、または口頭として使用しないでください。

  • 商標登録されている用語を省略したり、ハイフンを付けたり、斜体にしたりしないでください。

  • 商標登録された用語を複数化してはいけません。複数形が必要な場合は、商標名を形容詞として使用し、複数形名詞を修正します。

  • 商標登録された用語の所有形態を使用してはいけない。ネットアップなど、ネットアップの会社名は、商標登録用語ではなく一般的な意味で使用されている場合に、独占的な形式を使用できます。

ユーザインターフェイス

ユーザインターフェイスを文書化する場合は、ユーザをガイドするために、できるだけインターフェイスに依存してください。

一般的なガイドライン

UIを文書化するときは、シンプルでシンプルなスタイルを使用します。

Details
  • ユーザーがコンテンツの読み取り中にインターフェイスを使用していると仮定します。

    • ウィザードや画面を段階的に操作しないでください。インターフェイスから明確でない重要な事項のみを呼び出します。

    • 「OKをクリック」、「保存をクリック」、「ボリュームが作成されました」など、タスクを実行している人にわかりやすいものは含めないでください。

    • 成功を想定します。ほとんどの場合、処理が失敗すると予想される場合を除き、障害パスは文書化しないでください。インターフェイスが適切なガイダンスを提供しているとします。

  • 「クリック」をまったく使用しないでください。その単語はマウス、タッチ、キーボード、その他の選択方法をカバーしているため、常に「選択」を使用してください。

  • お客様のユースケースに対応し、ワークフローを開始するためにユーザをインターフェイス内の適切な場所に配置するためのワークフローに、コンテンツを集中的に配置します。

  • ユーザーの目標を達成するための最良の方法の 1 つを常に文書化してください。

  • ワークフローで重大な決定が必要な場合は、必ず決定規則を文書化してください。

  • ほとんどのユーザには、最低限必要な手順を使用します。

UI 要素に名前を付ける

UI 要素に名前を付ける必要がある細分性レベルにドキュメント化しないでください。

Details

インターフェイスを使用して、インタラクションの詳細をユーザーに説明します。特定のラベルを取得する必要がある場合は、そのラベルに名前を付けます。たとえば、「目的のボリュームを選択」または「既存のボリュームを使用」を選択します。 メニュー、ラジオボタン、チェックボックスに名前を付ける必要はありません。ラベルを使用するだけです。

ユーザーが選択する必要があるアイコンの場合は、アイコンの画像を使用します。名前を付けようとしないでください。このルール環境では、矢印、鉛筆、ギア、 kabob 、ハンバーガー、 など。

表示されているラベルを表します

ラベルを識別するときは、ユーザインターフェイスで使用されるスペルと大文字小文字の区別に従ってください。

Details

ラベルの後ろに省略記号が付いている場合は、オブジェクトの名前に省略記号を含めないでください。ユーザインターフェイスラベルにタイトルスタイルの大文字と小文字を使用して、ユーザインターフェイスラベルについて簡単に記述できるようにするように開発者に勧めてください。

スクリーンキャプチャを使用する

スクリーンキャプチャは慎重に使用してください。

Details

時折スクリーンキャプチャ(「スクリーンショット」)を使用すると、ワークフロー中にインターフェイスを開始または変更するときに、インターフェイス内の適切な場所にいることをユーザーが確信できるようになります。スクリーンキャプチャを使用して、入力するデータや選択する値を表示しないでください。

while(ただし)

  • 「while」は、時間内に発生したことを示すために使用します。

  • ほぼ同時に、または別のアクティビティの直後に発生するアクティビティを表すには、「though」を使用します。