檔指導方針 - MRTK2

MRTK

本檔概述Mixed Reality工具組 (MRTK) 的檔指導方針和標準。 這提供檔撰寫和產生的技術層面簡介、強調常見的陷阱,以及描述建議的書寫樣式。

頁面本身應該做為範例,因此它會使用預期的樣式和檔最常見的標記功能。


功能和標記

本節說明經常需要的功能。 若要查看其運作方式,請查看頁面的原始程式碼。

  1. 編號清單
    1. 具有至少 3 個前置空格的巢狀編號清單
    2. 程式碼中的實際數位無關;剖析會負責設定正確的專案編號。
  • 專案符號點清單
    • 巢狀專案符號清單
  • 使用 **double 星號** 以 粗體 顯示文字
  • 具有 _underscore_ 或 *單一星號* 的斜體文字
  • 句子中的文字 highlighted as code 'using backquotes'
  • 檔頁面MRTK 檔指導方針的連結
  • 頁面內錨點的連結;錨點的形成方式是將空格取代為虛線,並轉換成小寫

針對程式碼範例,我們會使用具有三個反引號 ''' 的區塊,並將 csharp 指定為語法醒目提示的語言:

int SampleFunction(int i)
{
   return i + 42;
}

在句子 use a single backtick 中提及程式碼時。

TODO

避免在檔中使用 TODO,因為這些 TODO 在一段時間後 (,例如程式碼 TODO) 通常會累積,以及更新方式及其遺失原因的相關資訊。

如果絕對需要新增 TODO,請遵循下列步驟:

  1. 在 Github 上提出描述 TODO 背後的內容的新問題,並提供足夠的背景,讓另一個參與者能夠瞭解並處理 TODO。
  2. 參考檔中待辦事項中的問題 URL。

<-- TODO https://github.com/microsoft/MixedRealityToolkit-Unity/issues/ISSUE_NUMBER_HERE :問題的簡短模糊 -->

醒目提示的區段

若要反白顯示讀取器的特定點,請使用> [!注意]> [!WARNING]> [!重要]以產生下列樣式。 建議只針對特殊相關案例使用一般點和警告/重要點的附注。

注意

附注的範例

警告

警告的範例

重要

重要批註的範例

頁面配置

簡介

主要章節標題後面的部分應該做為章節簡介的簡短簡介。 不要太長,而是新增子標題。 這些允許連結至區段,並可儲存為書簽。

主本文

使用兩層和三層標題來建構其餘部分。

迷你區段

針對應該醒目提示的區塊使用粗體文字行。我們可能會在某個時間點以四層標題取代此專案。

「另請參閱」一節

大部分的頁面應該以名為 See 的章節結尾。 本章只是與本主題相關頁面的連結點指向清單。 這些連結可能也會出現在適當的頁面文字中,但這並非必要專案。 同樣地,頁面文字可能包含與主要主題無關之頁面的連結,因此不應包含在 [另請參閱 ] 清單中。 請參閱 此頁面的「另請參閱」章節 作為連結選擇的範例。

目錄 (TOC)

Toc 檔案可用來在 MRTK github.io 檔中產生導覽列。 每當新增新的檔檔案時,請確定檔資料夾的其中一個 toc.yml 檔案中有該檔案的專案。 只有 toc 檔案中列出的文章會顯示在開發人員檔的導覽中。檔資料夾中每個子資料夾都可以有 toc 檔案,可以連結至任何現有的 toc 檔案,以將其新增為導覽對應部分的子區段。

樣式

撰寫樣式

一般經驗法則:嘗試 聲音專業。 這通常表示避免「交談語調」。 也請嘗試避免雙曲和感覺。

  1. 請勿嘗試過度) (。
  2. 永不寫入 'I'
  3. 請避免 'we'。 這通常可以輕鬆地重繪,改用 'MRTK'。 範例:「我們支援此功能」- > 「MRTK 支援此功能」或「支援下列功能...」。
  4. 同樣地,請嘗試避免「您」。 範例:「有了這個簡單的變更,您的著色器就會變成可設定的!- > 「著色器可以設定,而不需要太多心力。」
  5. 請勿使用 'sloppy phrases'。
  6. 避免聽起來過於興奮,我們不需要銷售任何專案。
  7. 同樣地,請避免過度明顯。 很少需要驚嘆號。

大寫

  • 針對 標題使用句子案例。即。將第一個字母和名稱大寫,但沒有其他專案。
  • 將一般英文用於其他所有專案。 這表示即使它們在該內容中具有特殊意義,也不會 將任意單字大寫。 偏好斜 體文字 來反白顯示特定單字, 請參閱下方
  • 當連結內嵌在句子中 (這是慣用的方法) 時,標準章節名稱一律會使用大寫字母,因此會中斷文字內沒有任意大寫的規則。 因此,使用自訂連結名稱來修正大小寫。 例如,以下是 界限控制項 檔的連結。
  • 請對名稱進行大寫,例如 Unity
  • 撰寫 Unity 編輯器時請勿將「編輯器」大寫。

強調和醒目提示

有兩種方式可以強調或醒目提示單字,使其粗體或使其斜體。 粗體文字的效果是粗 體文字會貼上 ,因此在流覽一段文字或甚至只是捲動頁面時很容易注意到。 粗體非常適合醒目提示人們應該記住的片語。 不過, 很少使用粗體文字,因為它通常會干擾。

通常,因為其具有特殊意義,所以想要「群組」某個專案以邏輯方式屬於一起或反白顯示特定字詞。 這類專案不需要醒目提示整體文字。 使用斜體文字作為 輕量型方法來 反白顯示某些專案。

同樣地,在文字中提及檔案名、路徑或功能表項目時,偏好讓它以邏輯方式分組,而不會干擾。

一般而言,請嘗試 避免不必要的文字醒目提示。 特殊字詞可以醒目提示一次,讓讀者知道,不要在文字中重複這類醒目提示,當文字不再有用途且只干擾。

提及功能表項目

提及使用者應該按一下的功能表項目時,目前的慣例是: 專案 > 檔 > 建立 > 分葉

盡可能插入其他頁面的實用連結,但每個連結只插入一次。 假設讀者按一下頁面上的每一個連結,並思考如果相同頁面開啟 20 次,該頁面會如何令人擔心。

偏好內嵌在句子中的連結:

  • BAD:指導方針很有用。 如需詳細資訊,請參閱 本章
  • 良好: 指導方針 很有用。

避免外部連結過期或包含著作權內容。

新增連結時,請考慮是否也應該列在 [另請參閱] 區段中。 同樣地,檢查是否應該將新頁面的連結新增至連結至頁面。

影像/螢幕擷取畫面

謹慎使用螢幕擷取畫面。 維護檔中的影像是許多工作,小型 UI 變更可能會使許多螢幕擷取畫面過期。 下列規則可減少維護工作:

  1. 請勿將螢幕擷取畫面用於文字中可描述的專案。 特別是,絕不會針對顯示內容名稱和值的唯一用途來 螢幕擷取畫面屬性方格
  2. 請勿在螢幕擷取畫面中包含與所顯示內容無關的專案。 例如,顯示轉譯效果時,請製作檢視區的螢幕擷取畫面,但排除其周圍的任何 UI。 顯示一些 UI,請嘗試四處移動視窗,只讓重要的部分位於影像中。
  3. 包含螢幕擷取畫面 UI 時,只顯示重要部分。 例如,在討論工具列中的按鈕時,製作顯示重要工具列按鈕的小型影像,但會排除其周圍的所有專案。
  4. 只使用容易重現的影像。 這表示不會將標記或醒目提示繪製到螢幕擷取畫面中。 首先,沒有任何一致的規則應該如何顯示這些規則。 其次,重現這類螢幕擷取畫面是額外的工作。 相反地,請描述文字中的重要部分。 此規則有例外狀況,但很少見。
  5. 很明顯地,重新建立動畫 GIF 會更加努力。 如果不想花費該時間,預期會負責重新建立到時間結束,或預期人們擲回該時間。
  6. 讓發行項中的影像數目保持低。 通常良好的方法是製作一個工具的整體螢幕擷取畫面,其中顯示所有專案,然後在文字中描述其餘部分。 這可讓您在必要時輕鬆地取代螢幕擷取畫面。

其他一些層面:

  • 螢幕擷取畫面的編輯器 UI 應該使用淺灰色主題編輯器,因為並非所有使用者都能存取深色主題,而且我們想要盡可能保持一致。
  • 預設影像寬度為 500 圖元,因為這在大部分監視器上都顯示良好。 請嘗試不要偏離太多。800 圖元寬度應該是最大值。
  • 針對 UI 的螢幕擷取畫面使用 PNG。
  • 針對 3D 檢視區螢幕擷取畫面使用 PNG 或 JPG。 偏好品質高於壓縮比例。

元件屬性清單

記錄屬性清單時,請使用粗體文字來反白顯示內容名稱,然後分行符號和一般文字來描述它們。 請勿使用子章或專案符號點清單。

此外,別忘了以句號完成所有句子。

頁面完成檢查清單

  1. 請確定已遵循本檔的指導方針。
  2. 流覽檔結構,並查看是否可以在其他頁面的 [另請參閱 ] 區段下提及新檔。
  3. 如果有的話,請讓具備主題證明知識的人員閱讀頁面以取得技術正確性。
  4. 讓某人證明閱讀頁面的樣式和格式。 這可以是不熟悉主題的人,這也是取得有關檔瞭解程度的意見反應的好主意。

來原始檔案

API 檔將會自動從 MRTK 來源檔案產生。 若要協助這樣做,需要來源檔案才能包含下列專案:

除了上述內容之外,程式碼也應該有良好的批註,以允許維護、錯誤修正和輕鬆自訂。

類別、結構、列舉摘要區塊

如果將類別、結構或列舉新增至 MRTK,則必須描述其用途。 這是採用 類別上方摘要區塊的形式。

/// <summary>
/// AudioOccluder implements IAudioInfluencer to provide an occlusion effect.
/// </summary>

如果有任何類別層級相依性,則應該記錄在備註區塊中,緊接在摘要下方。

/// <remarks>
/// Ensure that all sound emitting objects have an attached AudioInfluencerController.
/// Failing to do so will result in the desired effect not being applied to the sound.
/// </remarks>

不會核准未針對類別、結構或列舉摘要提交的提取要求。

屬性、方法、事件摘要區塊

不論程式碼可見度 (公用、私人、受保護和內部) ,屬性、方法和事件 (PME) 以及欄位都會記錄摘要區塊。 檔產生工具負責只篩選出和發佈公用和受保護的功能。

注意:Unity 方法 不需要 摘要區塊 (,例如:Awake、Start、Update) 。

提取要求需要PME 檔才能獲得核准。

作為 PME 摘要區塊的一部分,需要參數和傳回資料的意義和用途。

/// <summary>
/// Sets the cached native cutoff frequency of the attached low pass filter.
/// </summary>
/// <param name="frequency">The new low pass filter cutoff frequency.</param>
/// <returns>The new cutoff frequency value.</returns>

功能簡介版本和相依性

作為 API 摘要檔的一部分,有關引進此功能之 MRTK 版本的資訊,以及任何相依性都應該記載在備註區塊中。

相依性應包含延伸模組和/或平臺相依性。

/// <remarks>
/// Introduced in MRTK version: 2018.06.0
/// Minimum Unity version: 2018.0.0f1
/// Minimum Operating System: Windows 10.0.11111.0
/// Requires installation of: ImaginarySDK v2.1
/// </remarks>

序列化欄位

最好是使用 Unity 的工具提示屬性,為偵測器中的腳本欄位提供執行時間檔。

因此,API 檔中會包含組態選項,腳本 至少 必須在摘要區塊中包含工具提示內容。

/// <summary>
/// The quality level of the simulated audio source (ex: AM radio).
/// </summary>
[Tooltip("The quality level of the simulated audio source.")]

列舉值

定義和列舉時,程式碼也必須使用摘要區塊記錄列舉值的意義。 備註區塊可以選擇性地用來提供其他詳細資料,以增強瞭解。

/// <summary>
/// Full range of human hearing.
/// </summary>
/// <remarks>
/// The frequency range used is a bit wider than that of human
/// hearing. It closely resembles the range used for audio CDs.
/// </remarks>

操作說明文件

Mixed Reality工具組的許多使用者可能不需要使用 API 檔。 這些使用者會利用我們預先建立、可重複使用的預製專案和腳本來建立其體驗。

每個功能區域都會包含一或多個 Markdown (.md) 檔案,這些檔案會以相當高的方式提供。 視指定功能區域的大小和/或複雜度而定,可能需要額外的檔案,每個提供的功能最多一個。

新增功能 (或使用方式變更) 時,必須提供概觀檔。

在本檔中,應該提供操作說明章節,包括圖例,以協助客戶開始使用功能或概念。

設計檔

Mixed Reality提供機會來建立全新的世界。 其中一部分可能涉及建立自訂資產以與 MRTK 搭配使用。 為了讓客戶盡可能無摩擦,元件應該提供描述任何藝術資產格式或其他需求的設計檔。

設計檔可能有説明的一些範例:

  • 資料指標模型
  • 空間對應視覺效果
  • 音效檔案

強烈建議使用這種類型的檔,而且可能會在提取要求檢閱時要求。

這可能或可能與MS 開發人員網站上的設計建議不同

效能注意事項

某些重要的功能會產生效能成本。 此程式碼通常會視其設定方式而定。

例如:

When using the spatial mapping component, the performance impact will increase with the level of detail requested.  
It is recommended to use the least detail possible for the desired experience.

建議針對 CPU 和/或 GPU 繁重元件使用效能注意事項,而且 可能會在 提取要求檢閱過程中要求。 任何適用的效能注意事項都會包含在 API 概觀檔中。

重大變更

重大變更檔是由最上層 檔案 所組成,其連結至每個功能區域的個別 breaking-changes.md。

功能區域 breaking-changes.md 檔案包含指定版本的所有已知重大變更清單 ,以及 過去版本中重大變更的歷程記錄。

例如:

Spatial sound breaking changes

2018.07.2
* Spatialization of the imaginary effect is now required.
* Management of randomized AudioClip files requires an entropy value in the manager node.

2018.07.1
No known breaking changes

2018.07.0
...

功能層級中包含的資訊 breaking-changes.md 檔案將會匯總至每個新 MRTK 版本的版本資訊。

任何屬於變更的中斷性變更 都必須 記載為提取要求的一部分。

編輯 MarkDown 的工具

Visual Studio Code是編輯屬於 MRTK 檔一部分之 Markdown 檔案的絕佳工具。

撰寫檔時,也強烈建議安裝下列兩個延伸模組:

  • docs Markdown Extension for Visual Studio Code - 使用 Alt+M 來顯示檔撰寫選項的功能表。

  • 程式碼拼字檢查工具 - 拼錯字組會加上底線;以滑鼠右鍵按一下拼錯的字組來變更它,或將它儲存至字典。

這兩者都封裝在 Microsoft 發佈的 Docs Authoring Pack 中。

另請參閱