Proyecto BRL-CAD

Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.

Resumen del proyecto

Organización de código abierto:
BRL
Escritor técnico:
Sahibkaur
Nombre del proyecto:
Guía para principiantes sobre BRL-CAD
Duración del proyecto:
Duración estándar (3 meses)

Project description

Guía para principiantes sobre BRL-CAD

Resumen del proyecto

El objetivo de este proyecto es crear documentación destinada a los usuarios que no solo sean nuevos en BRL-CAD, sino también en el código abierto.

Por qué este proyecto

Cuando visité el sitio web de BRL-CAD por primera vez, como era nuevo en el uso del código abierto y el BRL-CAD, me abrumó la cantidad de información de una sola vez. Pero, en el fondo, sabía que había mucho que aprender aquí. Por lo tanto, quería crear documentación para usuarios nuevos como yo a fin de aprovechar mucho esta comunidad y sentirse tranquilo para comenzar.

Objetivos

Este proyecto se orientará a usuarios nuevos. Estos son algunos de los puntos que tengo como objetivo lograr con mi documentación: Garantizar que los nuevos usuarios se sientan tranquilos: esta documentación es para usuarios nuevos, no solo que usan BRL-CAD, sino también que usan código abierto.

Para lograrlo, haré lo siguiente:

  • Asegúrate de mantener la calificación de Flesch-Kincaid del documento al menos por encima de 50. Según el método de Flesch-Kincaid, cuanto más alta es la puntuación, más fácil es entender la pieza. Puedes consultar su puntuación de legibilidad en línea.
  • Usa listas numeradas o con viñetas para que los lectores no se aburran ni se distraigan con párrafos largos.
  • Usa párrafos y oraciones más cortos, ya que requiere comparativamente más trabajo mental para leer y comprender oraciones más largas.
  • Usa subtítulos para dividir el texto. Documentación bien estructurada: la documentación bien estructurada desempeña un papel fundamental a la hora de guiar a los usuarios nuevos. Esto evita que se pierdan y les permite saber hacia dónde se dirigen y qué están haciendo. Para lograrlo, creé un mapa mental aproximado que puede ayudarnos a documentar esta guía para principiantes de manera organizada.

Descripción del proyecto

Este proyecto se centra en escribir documentación para que los nuevos usuarios puedan utilizar este software.

A continuación, se muestra un ejemplo de cómo pretendo hacer que la documentación sea más descriptiva.

Introducción básica: BRL-CAD (que se pronuncia “be-are-el-cad”) es un diseño de modelado sólido asistido por computadora (CAD) de geometría sólida constructiva (CSG). Es un potente sistema de modelado sólido, multiplataforma y de código abierto para el diseño 3D asistido por computadora y la visualización gráfica. ¿No puedes entenderlo? Veamos esto en detalle: De código abierto: Es un software con código fuente que cualquiera puede inspeccionar, modificar y mejorar. Dado que BRL-CAD es un software de código abierto, te invitamos a contribuir y hacer que BRL-CAD sea mejor que antes. Diseño asistido por computadora (CAD): en palabras simples, el CAD es el uso de programas informáticos para crear representaciones gráficas bidimensionales o tridimensionales de objetos físicos. Sistema de modelado sólido: El BRL-CAD se centra en el CAD de modelado sólido. El modelado de sólidos se distingue de otras formas de modelado geométrico porque hace hincapié en la precisión física y la descripción completa del espacio 3D. Simula un objeto de forma interna y externa. Geometría sólida constructiva (CSG): CSG permite representar modelos complejos como una serie de operaciones booleanas entre primitivas. Los objetos sólidos más simples que se usan para la representación se denominan primitivos. Para comprender CSG en un nivel básico, visita este vínculo.

*Como se menciona en la descripción de la idea del proyecto: La documentación abarcará mínimamente la instalación básica, una descripción general de las capacidades, de los principios de modelado de BRL-CAD, el uso básico de las herramientas principales, la creación de modelos, la importación y exportación, el análisis y la renderización.

Allí encontrarás introducciones breves sobre cómo abordaremos cada parte en la documentación.

  • Instalación básica: Agregaré un tutorial paso a paso para instalar el software BRL-CAD junto con las capturas de pantalla correspondientes. El tutorial para novatos es un buen lugar para empezar con los usuarios nuevos. Algunas de las cosas que encuentro que faltan son las siguientes:
  • Los pasos de este tutorial para principiantes no tienen viñetas ni están numerados. Tener un tutorial paso a paso con una captura de pantalla al final de cada paso hace que sea más probable que el usuario se enganche con el tutorial.
  • Descripción general de las capacidades: esta sección contendrá todas las áreas en las que BRL-CAD tiene el poder de mostrar maravillas. Un enfoque diagramado será una mejor manera de llamar la atención hacia esta parte.
  • Principios del modelado de BRL-CAD: Esta parte requerirá más explicaciones porque el usuario podrá comprender mejor BRL-CAD una vez que comprenda bien estos principios para el modelado.
  • Uso básico de las principales herramientas: en este, tendremos tutoriales independientes de las principales herramientas y su uso básico. Estos serán instructivos paso a paso.
  • Exportación/Importación: Los usuarios conocerán la biblioteca de conversiones de geometría. Uno de los usos más comunes de BRL-CAD es convertir la geometría de un formato a otro. En esta sección, analizaremos los convertidores de importación y exportación.
  • Procesamiento: Abordaremos los conceptos básicos de la renderización y la necesidad en nuestro software. Además, los usuarios sabrán cómo renderizar imágenes en BRL-CAD.

Aparte de eso, la atención se centra también en los siguientes puntos:

  • Al comienzo de la documentación, comprenderás de qué se trata este software.
  • Cómo se pueden conectar los usuarios con esta comunidad de código abierto; vínculo al chat de Zulip en BRL y CAD.
  • En un nivel abstracto, usar la documentación un poco humorística y pedirles a los usuarios nuevos que no se desanimen con las palabras largas. Me gustó el enfoque empático utilizado en la página principal de la wiki de BRL-CAD.
  • Incluirá capturas de pantalla de las cosas increíbles que los usuarios pueden hacer con este software.

Logros

Julio (período de revisión de la propuesta)

  • Me familiarizaré más con el software y sus documentos wiki a medida que revisé los tutoriales existentes.
  • Voy a realizar mejoras en los documentos existentes.

Del 1 de agosto al 7 de agosto (vinculación con la comunidad)

  • Conversar con los mentores sobre el proyecto.
  • Definir mejor los detalles del proyecto.
  • Realiza los cambios necesarios en los hitos (si es necesario).

Del 8 al 14 de agosto

  • Familiarízate con el XML de Docbook

Del 15 al 21 de agosto

  • Escritura de documentación “Introducción básica al BRL-CAD”
  • Redacción del instructivo paso a paso de “Instalación básica”

Del 22 al 27 de agosto

  • Explorar varias capacidades de BRL-CAD y enumerarlas junto con capturas de pantalla
  • Explica las características individuales en una página aparte.

Del 28 de agosto al 3 de septiembre

  • Sigue trabajando en documentos individuales para las funciones.

4 de septiembre - 10 de septiembre

  • Trabajar en los principios del modelado.
  • Se explican todos los principios del modelado.

Del 11 al 17 de septiembre

  • Trabajar en el uso básico de las principales herramientas
  • Haz una lista reducida de ideas para documentar el uso básico de cada herramienta.

Del 18 al 24 de septiembre

  • Documentar el uso de cada herramienta

Del 25 de septiembre al 1 de octubre

  • Trabaja en Modelado para crear un modelo sólido para el instructivo y escribe un borrador junto con él.

Del 2 al 8 de octubre

  • Mejorar el borrador del modelado

Del 2 al 8 de octubre

  • Estudiar convertidores de importación y exportación

Del 9 al 15 de octubre

  • Preparar documentos de importación y exportación
  • Comienza a trabajar en la renderización.

Del 16 al 22 de octubre

  • Documenta el instructivo de renderización.

Del 23 al 29 de octubre

  • Revisar todos los documentos

Del 30 de octubre al 5 de noviembre

  • Cómo trabajar en el XML de Docbook

Del 6 al 12 de noviembre

  • Pide opiniones a mentores y otros miembros de la comunidad, y trabaja en los cambios.
  • Conversar con los mentores y hacer los cambios finales.

Del 12 al 22 de noviembre

  • Proceso de análisis y cambios.
  • Dar el toque final a la documentación.

Acerca de mí

Desde mis días de colegio, me comprometo a escribir. Cuando llegaba a casa de la escuela, escribía todo sobre mi día, qué hacía mejor o peor. Siempre tuve ganas de escribir los errores que cometí y cómo puedo mejorarlos.

Durante mi formación como diseñador web, nos pidieron que escribiéramos lo que aprendíamos a diario. Documentaba algunos de los problemas que enfrenté y la solución a ellos.

Como persona, siempre doy mi mejor pie para ayudar a los demás. Durante la escuela y la universidad, les explicaba algunos temas a mis amigos después de comprenderlos yo mismo. Participar en GSoD es un paso espléndido a través del cual yo, como escritor, puedo contribuir a hacer que esta comunidad de código abierto sea más atractiva y útil para los usuarios nuevos de todo el mundo.