本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- HPX
- 技術文件撰寫者：
- rstobaugh
- 專案名稱：
- 編輯並簡化現有的 HPX 說明文件
- 專案長度：
- 標準長度 (3 個月)
Project description
我提議編輯並簡化現有 HPX 說明文件的內容。我的提案適用於一個標準學期 (三個月) 專案，主要內容是修改 STE||AR 集團手冊的兩個章節：「HPX 建構系統和啟動」(1) 和「設定 HPX 應用程式」(2)。
《HPX Build System and Launching》(HPX 建構系統和啟動) 章節含有幾個文法錯誤，並且包含令人困惑的語言和不一致的大小寫 (例如「CMake」)。此外，其中含有重複資訊，我計劃視需要重新排列、合併和剪輯。「設定 HPX 應用程式」一節也包含一些需要解決的文法錯誤，但本章節主要的問題是對使用者的友善程度。此章節有三個我打算解決的三個主要設計問題：
有些標題藏在文字中，難以快速瀏覽各個章節。 目前，使用者需要詳閱手冊，瞭解每個資料表的用途。這並不是大多數使用者與指示手冊互動的方式，尤其如果使用者先前已經閱讀過這些內容，更是如此。我打算確定每個表格都有清楚且明確的標題，當使用者捲動文字時，才能看見這項資訊。
在特定標題下列出各項屬性時，這些屬性不會按照邏輯順序排列。 依照共同主題將屬性分組，但不會有子分組，讓資訊看起來有點分散。舉例來說，使用者可能會發現好幾個與縣市有關的房源，其中一些屬性涉及另一個主題，接著又有其他與縣市有關的地方。因為缺少標題的內部架構，較難找到特定主題的所有資訊。因此，我打算重新整理幾張圖表，在每個標題下更明確地將相似資訊分門別類。
使用者必須來回切換不同部分 (或在兩個不同分頁中開啟手冊)，才能完全瞭解特定指示。 章節會在某些時間點將使用者導向前一個章節，並強迫讀者向上捲動或點選超連結，以便瞭解確切的操作說明，因為該章節會手動使用較籠統的語言，例如上一節「步驟 11 後即預先建立此步驟」。這個方法確實可避免重複，但由於這些是必須按照特定順序排列的工作，因此指示將難以理解。因此，我建議你加入更具體的措辭，讓使用者不必因切換不同章節或文件而中斷閱讀。
如果我在標準時程表結束前完成這些章節，也希望清除 STE||AR 群組使用者說明文件下方的「為什麼要使用 HPX？」 (3) 頁面。本頁含有重複介紹內容，我們希望加以合併，其中含有不一致的大小寫 (尤其是專業術語) 和語氣，讓使用者感覺會有所不同。我的目標是要建立更一致且一致的 STE||AR 團隊的工作。