本頁面包含 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 (發音為 be-are-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 wiki 主頁面採用的同理心態做法。
- 其中包含使用者可透過這項軟體完成的驚人功能螢幕截圖。
里程碑
7 月 (提案審查期間)
- 我會在閱讀現有教學課程的同時，進一步熟悉軟體和其 Wiki 說明文件。
- 我會改善現有的文件。
8 月 1 日至 8 月 7 日 (社群凝聚)
- 與導師討論專案相關事宜。
- 調整專案詳細資料。
- 視需要在里程碑中進行必要變更。
8 月 8 日 - 8 月 14 日
- 熟悉 Docbook XML
8 月 15 日 - 8 月 21 日
- 撰寫「BRL-CAD 基本介紹」說明文件
- 撰寫「基本安裝」的逐步教學課程
8 月 22 日至 27 日
- 探索 BRL-CAD 的各種功能，並將這些功能和螢幕截圖列出。
- 在個別頁面中說明個別功能。
8 月 28 日 - 9 月 3 日
- 繼續處理各項功能的個別文件。
9 月 4 日 - 9 月 10 日
- 研究模擬原則。
- 說明所有建模原則。
9 月 11 日至 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 日
- 使用 Docbook XML
11 月 6 日 - 11 月 12 日
- 請導師和其他社群成員提供意見，並著手進行修改。
- 與導師討論，做出最終調整。
11 月 12 日至 11 月 22 日
- 討論與變更流程。
- 完成說明文件的最後修飾。
個人簡介
我從學生時代就喜歡寫作，我會在放學後寫下當天發生的事，包括哪些事情讓我感到開心或難過。我一向積極把自己犯的錯寫起來，看看該如何著手。
在擔任網頁設計師的訓練期間，我們被要求每天記錄學到的內容。我會記錄自己遇到的一些問題和解決方法。
我一直都盡力幫助他人。在求學期間，我會在自己瞭解某些主題後，向朋友解釋這些主題。參與 GSoD 是相當有趣的步驟，我身為作者，可以為這個開放原始碼社群貢獻一己之力，讓世界各地的新使用者享有更棒、更實用的體驗。