本頁詳細說明 Google 文件季度接受的一項技術撰寫專案詳細資料。
專案摘要
- 開放原始碼組織：
- BRL-CAD
- 技術撰稿人：
- sahibkaur
- 專案名稱：
- 巴西雷亞爾的新手指南
- 專案長度：
- 標準長度 (3 個月)
Project description
巴西雷亞爾的新手指南
專案摘要
這項專案旨在建立說明文件，對像不只是 BRL-CAD 新手，也對開放原始碼新手。
為何選擇這項專案
當我第一次造訪 BRL-CAD 網站時，因為我剛接觸開放原始碼和 BRL-CAD，一路收集的資訊量太多，卻不知從何著手。但是在講解中，我知道這裡有很多值得學習的地方。因此，我想建立說明文件，方便像我這樣的新使用者進一步參與社群，並輕鬆上手。
目標
這項專案將鎖定新使用者。因此，我的說明文件能夠達到以下目標： 為確保新使用者感到安心
為實現這個目標，我會：
- 請確保文件的 Flesch-Kincaid 得分至少維持在 50 分以上。根據 Flesch-Kincaid 方法，分數越高，越容易理解。您可以在線上查看其可讀性分數。
- 使用項目符號或編號清單，避免閱讀長段落而感到無聊或分心。
- 使用較短的段落和句子，因為要閱讀和理解較長的句子，需要花費相對比較多的心理工作。
- 使用子標題分散文字。 結構清晰的說明文件：對於引導新使用者，結構完善的說明文件扮演至關重要的角色。這種做法可以避免他們失蹤，並讓他們知道目前的進展與進展。 為了達成這個目標，我製作了一份粗糙的心智圖，可以幫助我們以有條理的方式記錄這份新手指南。
專案說明
本專案著重在撰寫說明文件，讓新使用者瞭解這項軟體。
以下提供範例，說明我打算如何讓說明文件更加淺顯易懂。
基本介紹：BRL-CAD (發音為 be-are-cad) 是一種具建設性的固體幾何圖形 (CSG) 實體與電腦輔助設計 (CAD)。Cloud Run 是功能強大的跨平台開放原始碼建模系統，專為 3D 電腦輔助設計與圖形視覺化而設計。 自己沒辦法動頭嗎？以下為你詳細說明。 開放原始碼：開放原始碼軟體是一種含有原始碼的軟體，任何人都可以進行檢查、修改及強化。BRL-CAD 是開放原始碼軟體，歡迎各位貢獻心力，讓 BRL-CAD 更臻完善！ 電腦輔助設計 (CAD)：簡單來說，CAD 是指運用電腦程式建立二維或 3D 圖形呈現實體物件。固體建模系統：BRL-CAD 著重於固體模型 CAD。實體模型與其他形式的幾何模型不同，主要在於注重物理準確性，並完整描述 3D 空間。此 API 會在內部和外部模擬物件。建築固體幾何圖形 (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 日
- 認識 Docbook 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 日
- 處理 Docbook XML
11 月 6 日至 11 月 12 日
- 請詢問導師和其他社群成員的評論，並自行修改。
- 與導師討論，做出最終修改。
11 月 12 日至 11 月 22 日
- 討論與變更流程。
- 為說明文件做出最終調整。
個人簡介
我從學校寫信了，我出門回家後，全程寫下我的一天；我的一天真是美好或更差的事情。我一直都很想把出錯的部分寫下來，然後想知道該如何改善。
擔任網頁設計人員時，我們要求寫下每天學到的內容。我會記錄一些我遇到的問題和解決方法。
身為人類的我，我會盡力協助他人。在學校和大學期間，我會向朋友說明幾個主題，再由自己瞭解這些主題。 加入 GSoD 是相當令人振奮的階段，我身為作家的我，貢獻了這個開放原始碼社群對世界各地的新使用者貢獻心力。