BRL-CAD 專案
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
本頁面包含 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 日
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 日
11 月 6 日 - 11 月 12 日
- 請導師和其他社群成員提供意見，並著手進行修改。
- 與導師討論，做出最終調整。
11 月 12 日至 11 月 22 日
個人簡介
我從學生時代就喜歡寫作，我會在放學後寫下當天發生的事，包括哪些事情讓我感到開心或難過。我一向積極把自己犯的錯寫起來，看看該如何著手。
在擔任網頁設計師的訓練期間，我們被要求每天記錄學到的內容。我會記錄自己遇到的一些問題和解決方法。
我一直都盡力幫助他人。在求學期間，我會在自己瞭解某些主題後，向朋友解釋這些主題。參與 GSoD 是相當有趣的步驟，我身為作者，可以為這個開放原始碼社群貢獻一己之力，讓世界各地的新使用者享有更棒、更實用的體驗。
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-07-25 (世界標準時間)。
[null,null,["上次更新時間：2025-07-25 (世界標準時間)。"],[[["\u003cp\u003eThis project aims to create a beginner-friendly guide for BRL-CAD, focusing on clear explanations, organized structure, and ease of navigation.\u003c/p\u003e\n"],["\u003cp\u003eThe documentation will cover topics such as installation, capabilities, modeling principles, tools usage, import/export, and rendering.\u003c/p\u003e\n"],["\u003cp\u003eIt emphasizes simple language, visual aids, and practical examples for new users, particularly those unfamiliar with open-source software.\u003c/p\u003e\n"],["\u003cp\u003eThe project involves step-by-step tutorials, diagrams, and a comprehensive overview of BRL-CAD's functionalities, making it easier to learn and use.\u003c/p\u003e\n"],["\u003cp\u003eThis guide encourages new users to join the BRL-CAD open-source community and contribute to the software's development.\u003c/p\u003e\n"]]],["The technical writing project focuses on creating a \"Beginner's Guide to BRL-CAD\" for new users, including those new to open-source. Key actions include: creating easy-to-understand documentation using specific writing techniques like short sentences, lists, and subheadings; breaking down complex terminology; providing step-by-step tutorials for basic installation and major tools; and covering capabilities, modeling principles, import/export, and rendering. The guide will have an empathetic, engaging, and humorous tone and will connect users to the community. The writer will also study and document with Docbook XML.\n"],null,["# BRL-CAD project\n\nThis page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\nProject summary\n---------------\n\nOpen source organization:\n: BRL-CAD\n\nTechnical writer:\n: sahibkaur\n\nProject name:\n: A Beginner's Guide To BRL-CAD\n\nProject length:\n: Standard length (3 months)\n\nProject description\n-------------------\n\nA Beginner's Guide To BRL-CAD\n\n### Project Abstract\n\nThis project aims at creating documentation dedicated to users who are not only new to BRL-CAD but also new to open-source.\n\n### Why this project\n\nWhen I first visited the BRL-CAD website, as I was new to open-source and BRL-CAD, I got overwhelmed by the amount of information at one go. But deep down, I knew there is a lot to learn here. So, I wanted to create documentation for new users like me to get a lot out of this community and feel at ease to get started with.\n\n### Goals\n\nThis project will target new users. So, following are some points my documentation aims to achieve:\nTo ensure new users feel at ease: Since this documentation is for new users not only new to BRL-CAD but also new to open-source.\n\nTo achieve this, I will:\n\n- Make sure to keep the Flesch-Kincaid score of the document at least above 50. According to the Flesch-Kincaid method, the higher the score, the easier the piece is to understand. You can check its readability score online.\n- Use bulleted or numbered lists so that readers do not get bored or distracted by long paragraphs.\n- Use shorter paragraphs and sentences because it requires comparatively more mental work to read and understand longer sentences.\n- Use subheadings to break up the text. Well-structured documentation: Well-structured documentation plays a crucial role in guiding new users. It prevents them from getting lost and, let them know where they are heading and what they are doing. To achieve this I have built a rough mind map which can help us document this beginner's guide in an organized way.\n\n### Project Description\n\nThis project focuses on writing documentation for new users to get their hands on this software.\n\nGiven below is an example of how I intend to make documentation more descriptive.\n\nBasic Introduction:\nBRL-CAD (pronounced be-are-el-cad) is a constructive solid geometry (CSG) solid modeling computer-aided design (CAD). It is a powerful, cross-platform, open-source solid modeling system for 3D computer-aided design and graphic visualization.\nCan't get your head around it? Let's break it down.\nOpen-source: Open source software is a software with source code that anyone can inspect, modify, and enhance. BRL-CAD being an open-source software welcomes you to contribute and make BRL-CAD better than before!\nComputer Aided Design (CAD): In simple words, CAD is the use of computer programs to create two or three dimensional graphical representation of physical objects.\nSolid modeling system: BRL-CAD focuses on solid modeling CAD. Solid modeling is distinguished from other forms of geometric modeling by an emphasis on being physically accurate, fully describing 3D space. It simulates an object both internally and externally.\nConstructive Solid Geometry (CSG): CSG allows to represent complex models as a series of Boolean operations between primitives. The simplest solid objects used for the representation are called primitives.\nTo understand CSG on a fundamental level, visit [here](https://www.uni-salzburg.at/fileadmin/multimedia/Mathematik/images/EMMA/Workshop_Turkey/education_days/CSG_Haslinger_low_quality.pdf).\n\n\\*As mentioned in the project idea description:\nThe documentation will minimally cover basic installation, an overall description of capabilities, of BRL-CAD's modeling principles, basic usage of major tools, modeling, import/export, analysis, and rendering.\n\nLined up are brief intros to how I will cover each part in the documentation.\n\n- Basic Installation: I will add a step by step tutorial to install BRL-CAD software along with required screenshots. The tutorial for newbie is a nice place for new users to begin with. Some of the things I find missing are:\n- The steps of this beginner's tutorial are not bulleted or numbered. Having a step-by-step tutorial with a screenshot at the end of each step makes it more likely for the user to get hooked to the tutorial.\n- An overall description of capabilities: This section will contain all the areas where BRL-CAD has the power to show wonders. A diagrammatic approach will be a better way to grab attention towards this part.\n- BRL-CAD's modeling principles: This part will require more explanation because the user can better understand BRL-CAD once they get a solid grasp on these modeling principles.\n- Basic usage of major tools: Under this, we will have separate tutorials of the major tools and their basic usage. These will be step-by-step tutorials.\n- Export/Import: Users will get to know about Geometry Conversion Library. One of the most common uses of BRL-CAD is to convert geometry from one format to another. Under this section, we discuss export and import converters.\n- Rendering: We will cover the basics of rendering and the need for it in our software. Users will also get to know how to render images in BRL-CAD.\n\nApart from that, the focus is also on following points:\n\n- The beginning of the documentation will have a basic understanding of what this software is all about.\n- How users can connect with this open-source community; link to the BRL-CAD zulip chat.\n- On an abstract level, making the documentation a little humorous and asking the new users not to get discouraged by big words. I liked the empathetic approach used in BRL-CAD wiki Main page.\n- It will have screenshots of some amazing things users can do using this software.\n\n### Milestones\n\nJuly (Proposal Review Period)\n\n- I will make myself more familiar with the software and its wiki docs while going through the existing tutorials.\n- I'll be making improvements in the existing docs.\n\nAugust 1 - August 7 (Community bonding)\n\n- Discussing with mentors about the project.\n- Refining the project details.\n- Make required changes in the milestones (if need be).\n\nAugust 8 - August 14\n\n- Get familiar with Docbook XML\n\nAugust 15 - August 21\n\n- Writing documentation for \"Basic Introduction to BRL-CAD\"\n- Writing step-by-step tutorial for \"Basic Installation\"\n\nAugust 22 - August 27\n\n- Exploring various capabilities of BRL-CAD and listing them down along with screenshots.\n- Explain individual features on a separate page.\n\nAugust 28 - September 3\n\n- Continue working on individual docs for capabilities.\n\nSeptember 4 - September 10\n\n- Working on Modeling Principles.\n- Explaining all modeling principles.\n\nSeptember 11 - September 17\n\n- Work on Basic Usage of Major tools.\n- Shortlist ideas to document basic usage of each tool.\n\nSeptember 18 - September 24\n\n- Documenting the usage of each tool.\n\nSeptember 25 - October 1\n\n- Work on Modeling to create a solid model for tutorial and write a draft alongside.\n\nOctober 2 - October 8\n\n- Improve the modeling draft.\n\nOctober 2 - October 8\n\n- Studying export and import converters.\n\nOctober 9 - October 15\n\n- Prepare export and import docs.\n- Start working on rendering.\n\nOctober 16 - October 22\n\n- Documenting the rendering tutorial.\n\nOctober 23 - October 29\n\n- Reviewing all the docs.\n\nOctober 30 - November 5\n\n- Working on the Docbook XML\n\nNovember 6 - November 12\n\n- Ask for reviews from mentors and other community members and work on the changes.\n- Discussing with mentors and making final changes.\n\nNovember 12 - November 22\n\n- Discussing and changes process.\n- Giving final touch to the documentation.\n\n### About me\n\nI have been into writing since my school days. I would come home from school and write all about my day; what made my day better or worse. I was always keen to write down the mistakes I made and how can I improve them.\n\nDuring my training as a web designer, we were asked to write down what we learn daily. I would document some of the problems I faced and the solution to it.\n\nAs a person, I always put my best foot forward to help others. During school and college days, I would explain some topics to my friends after understanding those topics myself.\nTaking part in GSoD is a splendid step through which I, as a writer, can contribute in making this open-source community more engaging and helpful for new users all around the world."]]
