This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- BRL-CAD
- Technical writer:
- sahibkaur
- Project name:
- A Beginner's Guide To BRL-CAD
- Project length:
- Standard length (3 months)
Project description
A Beginner's Guide To BRL-CAD
Project Abstract
This project aims at creating documentation dedicated to users who are not only new to BRL-CAD but also new to open-source.
Why this project
When 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.
Goals
This project will target new users. So, following are some points my documentation aims to achieve: To 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.
To achieve this, I will:
- 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.
- Use bulleted or numbered lists so that readers do not get bored or distracted by long paragraphs.
- Use shorter paragraphs and sentences because it requires comparatively more mental work to read and understand longer sentences.
- 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.
Project Description
This project focuses on writing documentation for new users to get their hands on this software.
Given below is an example of how I intend to make documentation more descriptive.
Basic Introduction: BRL-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. Can’t get your head around it? Let’s break it down. Open-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! Computer Aided Design (CAD): In simple words, CAD is the use of computer programs to create two or three dimensional graphical representation of physical objects. Solid 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. Constructive 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. To understand CSG on a fundamental level, visit here.
*As mentioned in the project idea description: The 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.
Lined up are brief intros to how I will cover each part in the documentation.
- 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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Apart from that, the focus is also on following points:
- The beginning of the documentation will have a basic understanding of what this software is all about.
- How users can connect with this open-source community; link to the BRL-CAD zulip chat.
- 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.
- It will have screenshots of some amazing things users can do using this software.
Milestones
July (Proposal Review Period)
- I will make myself more familiar with the software and its wiki docs while going through the existing tutorials.
- I’ll be making improvements in the existing docs.
August 1 - August 7 (Community bonding)
- Discussing with mentors about the project.
- Refining the project details.
- Make required changes in the milestones (if need be).
August 8 - August 14
- Get familiar with Docbook XML
August 15 - August 21
- Writing documentation for “Basic Introduction to BRL-CAD”
- Writing step-by-step tutorial for “Basic Installation”
August 22 - August 27
- Exploring various capabilities of BRL-CAD and listing them down along with screenshots.
- Explain individual features on a separate page.
August 28 - September 3
- Continue working on individual docs for capabilities.
September 4 - September 10
- Working on Modeling Principles.
- Explaining all modeling principles.
September 11 - September 17
- Work on Basic Usage of Major tools.
- Shortlist ideas to document basic usage of each tool.
September 18 - September 24
- Documenting the usage of each tool.
September 25 - October 1
- Work on Modeling to create a solid model for tutorial and write a draft alongside.
October 2 - October 8
- Improve the modeling draft.
October 2 - October 8
- Studying export and import converters.
October 9 - October 15
- Prepare export and import docs.
- Start working on rendering.
October 16 - October 22
- Documenting the rendering tutorial.
October 23 - October 29
- Reviewing all the docs.
October 30 - November 5
- Working on the Docbook XML
November 6 - November 12
- Ask for reviews from mentors and other community members and work on the changes.
- Discussing with mentors and making final changes.
November 12 - November 22
- Discussing and changes process.
- Giving final touch to the documentation.
About me
I 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.
During 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.
As 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. Taking 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.