NetApp文件樣式指南
建議變更
PDF
我們的風格是對話式且具同理心的、但我們仍保持專業水準並達到目標。撰寫NetApp文件內容時、請遵循下列準則。
以對話方式撰寫
在向專業同仁解釋內容時、請像您說話一樣寫下。以對話的方式撰寫文章、有助於與觀眾建立連結。
| 太正式 | 太隨意了 | 我們的風格 |
|---|---|---|
如果您遇到 BlueXP 分層問題、可以在叢集儀表板上檢視健全狀況狀態、以判斷錯誤發生的原因。健全狀況反映ONTAP 出功能不全系統和服務連接器的狀態。 |
當發生故障時、這並不有趣。不過別擔心、只要查看叢集儀表板即可瞭解發生了什麼事、以及受到了哪些影響。 |
發生故障時、 BlueXP 分層會在叢集儀表板上顯示「故障」健全狀況狀態。檢視狀態以取得有關故障的資訊。 |
在配置儲存設備之前、您必須先從 BlueXP 探索 ONTAP 叢集。探索完成後、您必須開啟工作環境以配置儲存設備。 |
您只需要先從 BlueXP 探索 ONTAP 叢集、然後開啟工作環境以開始資源配置儲存設備。簡單易用！ |
從 BlueXP 探索 ONTAP 叢集之後、請開啟工作環境以配置儲存設備。 |
啟動設定精靈時、請依照精靈中的指示設定節點、並將其加入叢集。下列步驟將逐步引導您完成精靈中的步驟。 |
此時會出現設定精靈（幾乎像魔術一樣）、引導您完成設定節點並將其加入叢集的簡單程序。 |
依照設定精靈中的指示設定節點、並將其加入叢集。 |
您可以從多種內容格式類型中進行選擇、以安裝及設定新系統。每種格式類型都提供完整的指示。選擇最符合學習方式的格式類型。 |
您要如何設定及安裝系統？我們提供多種內容格式類型的指示、但只有您知道自己喜歡學習的方式。 |
選擇內容格式類型、引導您完成系統的安裝與設定。 |
使用宮縮
宮縮會強化 A 交談式語調而且許多收縮都很容易理解和翻譯。
展開以深入瞭解
-
使用這些容易理解和翻譯的宮縮：
不是
您是
不是
我們就是
不是
就是這樣
不是
我們來吧
沒有
我們會（如果需要未來的緊張局勢）
不會
不會（如果未來需要緊張）
別這麼做
您將會（如果需要未來的緊張局勢）
-
請勿使用這類難以理解和翻譯的合約：
會的
應該有
不會
不該這麼做
可能有
別無他法
簡單寫入
避免使用大字詞和令人混淆的字詞。保持簡單。您正在向專業同仁說明一些內容、而非顯示您的詞彙。
-
而非此 ** ：「將使用者與您的 NetApp Cloud Central 帳戶分離。」
-
請這麼做 ** ：「從您的 NetApp Cloud Central 帳戶移除使用者。」
至少寫入
簡短簡單的句子可讓內容更容易閱讀或掃描。現在可以使用較長的句子、然後再用較短的句子來追蹤。就像這樣。
-
而非以下 ** ：「若要在 AWS 中的 Cloud Volumes ONTAP 系統和其他網路中的 ONTAP 系統之間複寫資料、您必須在 Amazon VPC 和其他網路之間建立 VPN 連線、例如 Azure vnet 或您的公司網路。」
-
請執行此動作 ** ：「網路之間的資料複寫需要透過 VPN 連線。例如、在 Amazon VPC 和公司網路之間、或在 AWS 和 Azure 之間。」
請自問下列事項：
-
使用者目前是否需要此內容？
-
使用者介面是否已充分引導使用者？如果沒有、可以簡單地新增哪些其他指引？
-
我可以用較少的字詞來呈現內容、而不會發出太正式或太隨意的聲音嗎？
-
我可以縮短或簡化一句長句、或將其分成兩句以上嗎？
-
我可以使用清單來讓內容更具掃描能力嗎？
-
我可以使用圖形來補充或取代文字區塊嗎？
主動寫入
避免被動式語音是技術寫作的標準規則、但當您想要進行對話時、請務必使用主動式語音。
作用中的語音
使用主動式語音、讓句子的主旨執行動詞的動作。這通常表示動詞遵循句子主題。主動式語音可保持清晰、清晰的寫入。除非您有特定理由使用被動式語音、否則請直接將主動式語音和位址使用者當作「您」使用。
以下是一些良好的主動式語音寫入範例。請寫下以下內容：
-
在部署第一個叢集之前、請先提供必要的權限。
-
如果系統關機不正確、介面會顯示警告訊息。
-
NetApp已收到合約。
被動式語音
被動式的行動者不清楚：
-
如果系統關機不正常、則會顯示警告訊息。
-
NetApp獲得合約。
在下列情況下使用被動式語音：
-
您不知道行動的執行者或執行者。
-
您想要避免將行動結果的使用者歸咎於使用者。
-
您無法寫下相關內容、例如一些必要資訊。
迫切心情
針對使用者動作清單的步驟、指令、要求和標題、請使用必要的情緒：
-
" 在「工作環境」頁面上、按一下「探索」、然後選取「 ONTAP 叢集」。 "
-
" 旋轉 CAM 把手、使其與電源齊平。 "
考慮使用必要的語音來取代被動式語音：
-
而非此 ** ：「部署第一個叢集之前、必須先提供必要的權限。」
-
請執行此動作 ** ：「在部署第一個叢集之前、請先提供必要的權限。」
避免使用必要的語音功能、將步驟內嵌在概念和參考資訊中。
如需其他動詞慣例、請參閱：
撰寫一致的內容
「像您在向專業同仁解釋某件事時所說的那樣」、代表每個人都有不同之處。我們專業但對話的風格有助於將我們與使用者連結起來、並增加多位作者之間的細微不一致之處：
-
專注於讓內容清楚且易於使用。如果所有內容都清楚且易於使用、則細微的不一致性並不重要。
-
在您撰寫的頁面中保持一致。
-
請務必遵循中的準則 專為全球觀眾撰寫。
使用內含語言
NetApp相信其產品文件不應包含任何具差別的專屬語言。我們所用的詞彙、可以讓我們與客戶建立正面關係、或是與客戶分離。尤其是書面文字、影響比意圖更重要。
當您為NetApp產品建立內容時、請避免使用可能被解讀為有損人格、具有種族色彩、存在或其他具有壓迫性的語言。請改用所有需要使用文件的人都能存取且歡迎使用的語言。例如、不要使用「主要/從屬」來取代「主要/次要」。
請先使用以人為本的語言、然後再使用殘障。
不要使用他、他、他、她、她 或是一般參考資料中的客戶。改為：
-
重新撰寫句子以使用第二個人（您）。
-
重新改寫句子、使其具有複數名詞和發音。
-
請使用「」或「 A 」、而非名詞（例如「文件」）。
-
請參閱人員的職務（例如、讀者、員工、客戶或客戶）。
-
請使用「人員」或「個人」一詞。
-
被視為包容性或排他性的字詞範例 *
| 包容性範例 | 專屬範例 |
|---|---|
主要 / 次要 |
主要 / 從屬 |
允許的清單 |
白名單 |
封鎖清單 |
黑名單 |
停止 |
終止 |
停止回應 |
掛起 |
結束或取消 |
中止 |
人員工時 |
工時 |
開發人員需要存取其開發環境中的伺服器、但不需要存取 Azure 中的伺服器。 |
開發人員需要存取其開發環境中的伺服器、但不需要存取 Azure 中的伺服器。 |
失明的人 |
視障人士 |
視力不佳的人 |
視覺障礙 |
請立即瞭解
每個頁面都應該從對使用者最重要的部分開始。我們需要找出使用者嘗試做什麼、並專注於協助他們達成目標。我們也應該在句子開頭加上關鍵字、以提升掃描能力。
請遵循以下一般句子準則：
-
準確。
-
避免使用填塞字詞。
-
請保持簡短。
-
使用格式化的文字或項目符號清單來醒目提示重點。
-
達成目標的範例 *
| 範例很好 | 不良範例 |
|---|---|
如果您的企業有嚴格的安全性原則、請使用資料傳輸加密功能、在不同網路中的 NFS 伺服器之間同步資料。 |
Cloud Sync 可以使用資料傳輸加密、將資料從一部 NFS 伺服器同步到另一部 NFS 伺服器。如果您有嚴格的安全原則來透過網路傳輸資料、加密資料有助於解決問題。 |
建立包含最常用樣式、格式和版面配置的文件範本、可節省時間。然後在建立新文件時使用範本。 |
範本是建立新文件的起點。範本可以包含常用的樣式、格式和版面配置。如果您經常為文件使用相同的頁面配置和樣式、請考慮建立範本。 |
Astra Control 提供三種作業模式、您可以指派給使用者、以謹慎控制 Astra Control 與雲端環境之間的存取。 |
Astra Control 可讓您為 AWS 帳戶中的使用者指派三種操作模式之一。這些模式可讓您根據 IT 原則、仔細控制 Astra Control 與雲端環境之間的存取。 |
使用大量視覺效果
大多數人都是視覺學習者。使用影片、圖表和螢幕擷取畫面來改善學習、細分文字區塊、並提供視覺提示、讓使用者瞭解工作指示中的位置。
-
請附上一句導程、說明下圖所示的影像：「下圖顯示背面板上的 AC 電源供應器 LED 。」
-
請參閱圖示的位置、如「追蹤」或「之前」、而非「上方」或「下方」。
-
在內嵌視覺強化功能上使用替代文字。
-
如果視覺效果與步驟有關、請在步驟後加上視覺效果、然後縮排以與步驟編號對齊。
螢幕擷取畫面的最佳實務做法：
-
每項工作包含的螢幕擷取畫面不超過 5 個。
-
請勿在螢幕擷取畫面中包含文字。請改用編號標註。
-
請謹慎選擇要加入的螢幕擷取畫面。螢幕擷取畫面可能會很快過期。
影片或動畫的最佳實務做法：
-
影片長度應在 5 分鐘以內。
建立可協助使用者達成目標的工作流程
使用者閱讀我們的內容以達成特定目標。使用者想要找到所需的內容、達成目標、然後回到家中。我們的工作不是要記錄產品或功能。我們的工作是記錄使用者目標。工作流程是協助使用者達成目標的最直接方法。
工作流程是一系列步驟或子任務、說明如何達成使用者目標。工作流程的範圍是完整的目標。
例如、建立磁碟區的步驟並不是工作流程、因為建立磁碟區本身並不是一個完整的目標。讓ESX伺服器可以使用儲存設備的步驟可能是工作流程。這些步驟不僅包括建立磁碟區、還包括匯出磁碟區、設定任何必要的權限、建立網路介面等。
工作流程衍生自客戶使用案例。工作流程只顯示達成目標的最佳方式之一。
根據使用者的目標來組織內容
根據使用者嘗試達成的目標來組織內容、協助使用者快速找到資訊。本標準適用於文件網站的目錄（導覽）、以及網站上顯示的個別頁面。
依下列方式組織內容：
- 左側導覽的第一個項目（高層）
-
根據使用者嘗試達成的目標來組織內容。例如、網站導覽中的第一個項目可能是「開始使用」或「保護資料」。
- 文件網站導覽中的第二層項目（中階）
-
圍繞構成目標的廣泛工作來組織內容。
例如、「開始使用」一節可能包含下列頁面：
-
準備安裝
-
安裝及設定 <product name>
-
設定授權
-
接下來您可以做什麼
-
- 個別頁面（詳細層級）
-
在每個頁面上、圍繞構成廣泛工作的個別工作來組織內容。例如、使用者需要準備安裝或設定災難恢復的內容。
頁面可以描述單一工作或多項工作。如果有多項工作、則應在頁面上的個別區段中說明。每一節應著重於單一學習或執行廣泛工作的各個層面。這可能包括一些完成工作所需的概念性和參考型資訊。
專為全球觀眾撰寫
我們的文件會被許多使用者讀取、他們的主要語言不是英文。我們使用 Neural Machine 翻譯工具或人力翻譯、將內容翻譯成其他語言。為了支援我們的全球觀眾、我們撰寫了易於閱讀且易於翻譯的內容。
請遵循以下準則、為全球對象撰寫文章：
-
寫下簡短的句子。
-
使用標準語法和標點。
-
一個字只代表一個意義、一個字則代表一個意義。
-
使用常見的收縮。
-
使用圖形來釐清或取代文字。
-
避免在圖形中內嵌文字。
-
避免在字串中有三個以上的名詞。
-
避免不清楚的先前者。
-
避免使用行話、說詞和比喻。
-
避免非技術範例。
-
避免使用硬退貨和間隔。
-
請勿使用幽默或諷刺。
-
請勿使用歧視性內容。
-
除非您是為特定人員撰寫文章、否則請勿使用有性別偏見的語言。
A至Z準則
主動式語音（相對於被動式語音）
請參閱 主動寫入。
讚不已
請使用下列標籤、分別識別主要內容流程的內容：
-
附註
請使用附註來取得必須與其他文字不同的重要資訊。避免使用者不需要的「注意事項」來瞭解工作或完成工作。
-
秘訣
請謹慎使用秘訣、因為我們的原則是永遠記錄預設的最佳實務資訊。如有必要、請使用TIP來包含最佳實務資訊、協助使用者輕鬆高效地使用產品或完成步驟或工作。
-
注意
請務必小心、告知使用者可能造成非致命或極度危險的人員傷害的情況或程序。
之後（而非「一次」）
-
請使用「之後」來表示時間順序：「請在插入電腦後開啟電腦。」
-
使用「一次」只表示「一次」。
此外
-
使用「同時」表示「額外」。
-
請勿使用「亦」來表示「或者」。
和/或
如果有的話、請選擇更精確的詞彙。如果兩個詞彙都不比另一個詞彙更精確、請使用「和 / 或」。
做為
請勿使用「 AS 」來表示「因為」。
使用（相對於「使用」或「搭配」）
-
當使用的實體為主旨時、請使用「使用」：「您可以使用「元件」功能表將新元件新增至儲存庫。」
-
您可以使用「使用」或「搭配」來開始句子、有時產品名稱可以接受這句話：「使用 SnapDrive 、您可以在 Windows 環境中管理虛擬磁碟和 Snapshot 複本。」
CAN （相對於「可能」、「可能」、「應該」或「必須」）
-
使用「 CAN 」表示功能：「您可以在此程序中隨時提交變更。」
-
使用「可能」來表示可能的情況：「下載多個程式可能會影響處理時間。」
-
請勿使用「可能」、這是含糊不清的、因為這可能表示能力或權限。
-
使用「應該」來指出建議但可選的行動。請考慮改用替代詞組、例如「我們推薦」。
-
避免使用「必須」、因為是 被動式。請考慮使用必要的聲音、將思考重述為指示。如果您使用「必須」、請使用它來指出必要的行動或條件。
資本化
幾乎所有內容都使用句子樣式的大寫（小寫）。僅資本：
-
第一個句子和標題字、包括表格標題
-
清單項目的第一字、包括句子片段
-
適當的名詞
-
文件標題和字幕（將所有主要字詞和五個以上字母的前置詞大寫）
-
UI元素、但必須在介面中大寫。否則、請使用小寫字母。
注意通知
請參閱 讚不已。
合約
使用 合約 以對話的方式撰寫。
確保（相對於「確認」或「驗證」）
-
使用「確保」表示「確定」。 視情況加入「那樣」：「確保插圖周圍有足夠的空白空間。」
-
切勿使用「確保」暗示承諾或保證：「使用 Cloud Manager 確保您可以在 ONTAP 叢集上佈建 NFS 和 CIFS 磁碟區。」
-
當您表示使用者應仔細檢查已存在或已發生的情況時、請使用「確認」或「驗證」：「確認叢集上已設定 NFS 」。
圖形
請參閱 使用大量視覺效果。
如果沒有
請勿自行使用「如果沒有」來指前一句：
-
而非這項 ：「電腦應該關閉。如果沒有、請將其關閉。 "
-
請執行下列操作：「確認電腦已關閉。」
如果（相對於「是」或「何時」）
-
使用「 IF 」表示條件、例如在「 if then then then then 」結構中。
-
當存在聲明或暗示的「或不」條件時、請使用「是」。為了簡化翻譯、最好將「無論是否」取代為「是否」。
-
使用「何時」表示時間過長。
必要的聲音
請參閱 主動寫入。
未來功能或版本
請勿提及即將推出的產品版本或功能的時間或內容、只能說某項功能或功能「目前不受支援」。
知識庫文章：參考
如有需要、請參閱內容中的KB（NetApp知識庫）文章。如需資源頁面和GitHub內容、請將連結放入執行中文字。
清單
資訊清單通常比文字區塊更容易掃描和吸收。請考慮以清單形式呈現複雜資訊、以簡化複雜資訊的方法。以下是一些一般準則、但請運用您的判斷力：
-
請確定清單的原因清楚明確。介紹完整句子、含分號的句子片段或標題的清單。
-
清單應包含兩到七個項目。一般而言、每個項目中的資訊越短、您可以新增的項目越多、但清單仍可掃描。
-
清單項目應盡可能掃描。避免讓清單項目無法掃描的文字區塊。
-
清單項目應以大寫字母開頭、且清單項目應以等量方式平行。例如、使用名詞或動詞來啟動每個項目：
-
如果所有清單項目都是完整的句子、請以句點結束。
-
如果所有清單項目都是句子片段、請勿以句點結束。
-
-
清單項目應以邏輯方式排序、例如字母順序或時間順序。
本地化
請參閱 專為全球觀眾撰寫。
極簡主義
請參閱 至少寫入。
數字
-
10和10以上的所有數字都使用阿拉伯數字、但以下情況除外：
-
如果您以數字開頭句子、請使用字詞、而非阿拉伯數字。
-
請使用字數（非數字）作為大約數字。
-
-
請使用少於10的數字。
-
如果句子包含少於10且大於10的混合數字、請在所有數字中使用阿拉伯數字。
-
如需其他數字慣例、請參閱 "Microsoft Writing Style指南"。
複利
我們會記錄NetApp產品、以及NetApp產品與協力廠商產品之間的互動。我們不會記錄協力廠商產品。我們不應將第三方內容複製並貼到文件中、也絕不應這麼做。
先決條件
必要條件可識別必須存在的條件、或使用者在開始目前工作之前必須完成的動作。
-
以標題識別內容的性質、例如「先決條件」、「開始之前」或「開始之前」。
-
如果有必要的話、請使用被動式語音做為必備字詞：
-
" 必須在叢集上設定 NFS 或 CIFS 。 "
-
" 您必須擁有叢集管理 IP 位址和管理員使用者帳戶密碼、才能將叢集新增至 Cloud Manager 。 "
-
-
視需要釐清先決條件：「必須在叢集上設定 NFS 或 CIFS 。您可以使用 System Manager 或 CLI 設定 NFS 和 CIFS 。 "
-
請考慮其他提供資訊的方法、例如是否應該將內容重新定位為目前工作的第一步：
-
先決條件：「您必須擁有必要的權限、才能部署第一個叢集。」
-
步驟：「提供部署第一個叢集所需的權限。」
-
先前（相對於「之前」、「上一個」或「之前」）
-
如有可能、請將「先前」改為「之前」。
-
如果您無法使用「之前」、請使用「之前」做為形容詞、來指的是之前發生的事情、或是重要性較高的順序。
-
使用「上一步」來指出之前未指定時間發生的事件。
-
請使用「前面」來指出之前發生的事件。
標點符號
保持簡單。一般而言、句子中包含的符號越多、所需的大腦細胞就越多。
-
在三個以上項目的敘述清單中、在結合（「 AND 」或「 OR 」）之前使用序列逗號（牛津逗號）。
-
限制使用分號和分號。
-
除非另有說明、否則請遵循下列詳細說明的語法、標點和拼字慣例：
自
使用「自」來表示時間過長。請勿使用「自」來表示「因為」。
該（相對於「何人」或「誰」）
-
使用 "那個 " （不含結尾的逗號）來介紹句子所需的子句。
-
即使句子中沒有英文內容、也請使用「那個」：「請確認電腦已關機。」
-
使用「目標」（加上結尾的逗號）來引入新增支援資訊的子句、但這句話並不需要。
-
使用「對象」來介紹提及人員的條款。
商標
我們的大多數技術內容中並未包含商標符號、因為範本中的法律聲明已經足夠。不過、我們使用時確實遵守所有使用規則 "NetApp商標詞彙"：
-
使用商標詞彙（含或不含符號）僅做為形容詞、不得做為名詞、動詞或詞彙。
-
請勿將商標字詞縮寫、連字號或斜體。
-
請勿將商標詞彙複數化。如果需要複數格式、請使用商標名稱作為形容詞、以修改複數名詞。
-
請勿使用商標詞彙的所有形式。您可以使用公司名稱（例如NetApp）的所有格式、在一般意義上使用這些名稱、而非商標術語。
使用者介面
記錄使用者介面時、請盡可能仰賴介面來引導使用者。
記錄 UI 時、請使用簡單且極簡的樣式。
Details
-
假設使用者在讀取內容時使用介面：
-
請勿逐步引導使用者完成精靈或畫面。只能從介面中指出不明顯的重要事項。
-
請勿包含「按一下確定」或「按一下儲存」或「建立磁碟區」、或是執行工作的人所能看到的任何其他內容。
-
假設成功。除非您預期大部分時間作業都會失敗、否則請勿記錄故障路徑。假設介面提供適當的指引。
-
-
請勿使用「按一下」。請務必使用「 SELECT 」、因為這個字涵蓋滑鼠、觸控、鍵盤及其他任何選擇方式。
-
將內容著重於處理客戶使用案例的工作流程、以及讓使用者在介面中找到適當位置來開始工作流程。
-
務必記錄達成使用者目標的最佳方法之一。
-
如果工作流程需要重大決策、請務必記錄決策規則。
-
大部分時間、請使用大多數使用者所需的最低步驟數。
避免記錄到需要命名UI元素的精細度層級。
Details
請仰賴介面來引導使用者瞭解互動的細節。如果您必須取得該特定項目、請在元素上命名該標籤。例如、「選擇所需的 Volume 」或「選擇「使用現有 Volume 」。 無需命名功能表或選項按鈕或核取方塊、只要使用標籤即可。
如需使用者必須選取的圖示、請使用圖示的影像。請勿嘗試命名。此規則適用於箭頭、鉛筆、齒輪、kabob、漢堡、 等等。
識別標籤時、請遵循使用者介面所使用的拼字和大寫。
Details
如果標籤後面接著省略符號、請勿在命名物件時加入省略符號。鼓勵開發人員將標題樣式的大寫字用於使用者介面標籤、以便更輕鬆地撰寫這些標籤。
請謹慎使用螢幕擷取畫面。
Details
偶爾的螢幕擷取（「螢幕擷取畫面」）可協助使用者在工作流程期間啟動或變更介面時、確信自己位於介面中的正確位置。請勿使用螢幕擷取畫面來顯示要輸入的資料或要選擇的值。
同時（相對於「儘管」）
-
使用「同時」來指出時間內發生的情況。
-
使用「儘管」來代表幾乎同時發生或在其他活動之後不久發生的活動。