本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- BRL-CAD
- 技術文件撰寫者：
- sahibkaur
- 專案名稱：
- BRL-CAD 新手指南
- 專案長度：
- 標準長度 (3 個月)
Project description
BRL-CAD 新手指南
專案摘要
這項專案旨在製作說明文件，適用對象為 BRL-CAD 新手和開放原始碼領域的新手。
這項專案的原因
我第一次造訪 BRL-CAD 網站時，是因為我第一次使用開放原始碼和 BRL-CAD，所以一次的資訊量龐大，讓人不知從何著手。但我就知道這裡有許多值得學習的內容。因此，我想為像我這樣的新使用者製作說明文件，讓他們充分學習這個社群，並輕鬆開始使用。
目標
這項專案將鎖定新使用者。因此，以下文件旨在達成以下目標： 為確保新使用者感到安心：本說明文件的適用對象為 BRL-CAD 新使用者，也剛接觸開放原始碼的使用者。
為此，我採取以下做法：
- 請確保文件的 Flesch-Kincaid 分數至少達到 50 分。根據 Flesch-Kincaid 方法，分數越高，說明片段越容易理解。您可以在線上查看其可讀性分數。
- 使用項目符號或編號清單，避免長篇報導閱讀文章。
- 使用較短的段落和句子，因為在閱讀及理解較長的句子時，需要花更多的心思。
- 使用子標題拆分文字。 架構清晰的文件：架構完整的說明文件在引導新使用者時扮演著關鍵角色。這樣他們就不會丟失，還能讓他們瞭解進度和正在進行的活動。 為此，我製作了一份粗略圖，方便我們以有條理的方式記錄這份新手指南。
專案說明
這項專案著重於撰寫文件，讓新使用者能實際熟悉這項軟體。
以下是我如何讓說明文件更清楚易懂的範例。
基本簡介： BRL-CAD (發音為-el-cad) 是具有建設性的固體幾何 (CSG) 固態電腦輔助設計 (CAD)。這是強大、跨平台的開放原始碼固態模型系統，適用於 3D 電腦輔助設計和圖形視覺化功能。無法感受到頭部嗎？以下將詳細說明。 開放原始碼：開放原始碼軟體是指包含原始碼的軟體，任何人都能檢查、修改及強化。BRL-CAD 是開放原始碼軟體，歡迎你貢獻一己之力，讓 BRL-CAD 發揮更大效益！電腦輔助設計 (CAD)：簡單來說，CAD 會使用電腦程式建立二或三維圖像呈現實體物件。固態建模系統：BRL-CAD 著重於固態模型 CAD。固態模型之所以與其他形式的幾何建模，主要是強調真實性且完整描述 3D 空間，在內部和外部模擬物件。建構固態幾何圖形 (CSG)：CSG 可將複雜模型以布林值之間的一系列布林運算表示。用於表示的最簡單實心物件稱為原始物件。如要深入瞭解 CSG，請前往這裡。
*如專案構想說明所述： 說明文件幾乎涵蓋基本安裝內容、整體功能說明、BRL-CAD 的建模原則、主要工具的基本用法、建模、匯入/匯出、分析和轉譯。
整組簡介會說明如何在說明文件中介紹各個部分。
- 基本安裝：我會新增安裝 BRL-CAD 軟體的逐步教學課程，以及所需的螢幕截圖。新手教學課程是新手入門教學的好幫手。我找不到某些資訊，包括：
- 本新手教學課程中的步驟並未使用項目符號或編號，在每步驟結束時附上螢幕截圖，逐步引導使用者熟悉教學課程內容。
- 功能的整體說明：這個部分包含 BRL-CAD 可以展現奇思的所有區域。圖表式的做法是將注意力吸引到這個部分的好方法。
- BRL-CAD 的模擬原則：唯有在掌握這些模擬原則後，使用者才能進一步瞭解 BRL-CAD，因此這部分需要提供更多說明。
- 主要工具的基本用法：在這個單元中，我們會分別提供主要工具及相關基本使用方式的教學課程。其中包含逐步教學課程。
- 匯出/匯入：使用者將瞭解幾何圖形轉換資料庫。BRL-CAD 最常見的用途之一，就是將幾何圖形從一種格式轉換成另一種格式。在本節中，我們會討論匯出和匯入轉換工具。
- 轉譯：我們會說明轉譯的基本概念，以及軟體中的轉譯需求。使用者也會知道如何以巴西里爾 (BRL-CAD) 顯示圖片。
除此之外，我們也會著重在下列要點：
- 本文件的開頭將對本軟體有基本的瞭解。
- 使用者如何與這個開放原始碼社群交流；連結至 BRL-CAD zulip 即時通訊。
- 從抽象層面來說，說明文件可以稍微幽默詼諧，並且要求新使用者不要受制於重要字詞。我喜歡在巴西里爾 (BRL-CAD) 維基百科中採取的同理心。
- 提供螢幕截圖，說明使用者可利用該軟體執行哪些令人期待的功能。
里程碑
7 月 (提案審查期)
- 進行現有的教學課程時，我會逐漸熟悉軟體和相關的維基文件。
- 我會在現有文件中改善這項功能。
8 月 1 日至 8 月 7 日 (社群交流)
- 與導師討論專案內容。
- 修正專案詳細資料。
- 視需要變更里程碑。
8 月 8 日至 8 月 14 日
- 熟悉文件專用 XML
8 月 15 日至 8 月 21 日
- 撰寫「BRL-CAD 基本簡介」的說明文件
- 撰寫「基本安裝」的逐步教學課程
8 月 22 日至 8 月 27 日
- 探索 BRL-CAD 的各種功能，並連同螢幕截圖一起列出。
- 在其他頁面中說明個別功能。
8 月 28 日至 9 月 3 日
- 繼續在個別文件中使用各項功能。
9 月 4 日至 9 月 10 日
- 制定模型開發原則
- 解釋所有建模原則。
9 月 11 日至 9 月 17 日
- 解決主要工具的基本用法。
- 使用候選清單，記錄各項工具的基本用法。
9 月 18 日至 9 月 24 日
- 記錄各項工具的使用情況。
9 月 25 日至 10 月 1 日
- 進行製作模型時，我們會建立用於教學課程的可靠模型，並撰寫草稿。
10 月 2 日至 10 月 8 日
- 改善模型草稿。
10 月 2 日至 10 月 8 日
- 正在研究匯出和匯入轉換工具。
10 月 9 日至 10 月 15 日
- 準備匯出及匯入文件。
- 開始轉譯作業。
10 月 16 日至 10 月 22 日
- 記錄轉譯教學課程。
10 月 23 日至 10 月 29 日
- 檢閱所有文件。
10 月 30 日至 11 月 5 日
- 使用文件簿 XML
11 月 6 日至 11 月 12 日
- 請詢問導師和其他社群成員的意見，並處理變更。
- 請與導師討論並進行最終變更。
11 月 12 日至 11 月 22 日
- 討論及變更程序：
- 最後一次輕觸說明文件。
關於我
我從上學以來就一直致力於寫字。我會在學校回家，寫完一天的事；為什麼會讓我一天心情更好或更差。我一直都樂於寫下自己犯的錯誤，並思考如何改善問題。
身為網頁設計師，在培訓期間，我們被要求寫下自己每天學到的內容。我會記錄一些我面臨的問題，並記錄下來的解決方法。
身為一名成員，我總是竭盡所能提供協助。學校和大學期間，會在自己瞭解這些主題後，向朋友說明幾個主題。 加入 GSoD 是成功的一步，我身為寫作家，就能為這個開放原始碼社群做出更多貢獻，造福世界各地的新使用者。