En esta página, se incluyen 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-CAD
- Redactor técnico:
- sahibkaur
- Nombre del proyecto:
- A Beginner's Guide To BRL-CAD
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Guía de BRL-CAD para principiantes
Resumen del proyecto
El objetivo de este proyecto es crear documentación dedicada a los usuarios que no solo tienen experiencia en BRL-CAD, sino que también usan el código abierto.
Por qué este proyecto
Cuando visité el sitio web de BRL-CAD por primera vez, como era nuevo en el código abierto y en BRL-CAD, me sentí abrumado por la cantidad de información disponible. Pero, en el fondo, sabía que había mucho que aprender. Por lo tanto, quería crear documentación para que los usuarios nuevos como yo aprovechen al máximo esta comunidad y se sientan a gusto para comenzar.
Objetivos
Este proyecto se segmentará para usuarios nuevos. A continuación, se incluyen algunos puntos que mi documentación pretende lograr: Garantizar que los usuarios nuevos se sientan a gusto: Esta documentación está dirigida a usuarios nuevos, no solo en BRL-CAD, sino también en código abierto.
Para lograrlo, haré lo siguiente:
- Asegúrate de mantener la puntuación de Flesch-Kincaid del documento por encima de 50. Según el método Flesch-Kincaid, cuanto más alta sea la puntuación, más fácil será de entender el texto. Puedes consultar su puntuación de legibilidad en línea.
- Usa listas con viñetas o numeradas para que los lectores no se aburran ni se distraigan con párrafos largos.
- Usa oraciones y párrafos más cortos, ya que requiere más trabajo mental leer y comprender oraciones más largas.
- Usa subtítulos para dividir el texto. Documentación bien estructurada: una documentación bien estructurada juega un papel fundamental para guiar a los usuarios nuevos. Evita que se pierdan y les informa adó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 forma organizada.
Descripción del proyecto
Este proyecto se enfoca en escribir documentación para que los usuarios nuevos puedan probar 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 (pronunciado be-are-el-cad) es un diseño asistido por computadora (CAD) de modelado sólido de geometría sólida constructiva (CSG). Es un sistema de modelado sólido potente, multiplataforma y de código abierto para el diseño asistido por computadora y la visualización gráfica en 3D. ¿No puedes entenderlo? Veamos esto en detalle: De código abierto: Se trata de software con código fuente que cualquiera puede inspeccionar, modificar y mejorar. Como software de código abierto, BRL-CAD te invita a contribuir y hacer que 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 en dos o tres dimensiones de objetos físicos. Sistema de modelado sólido: BRL-CAD se enfoca en el CAD de modelado sólido. El modelado sólido se distingue de otras formas de modelado geométrico por su énfasis en ser físicamente preciso y describir completamente el espacio 3D. Simula un objeto de forma interna y externa. Geometría sólida constructiva (CSG): La 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 la CSG a nivel fundamental, 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, los principios de modelado de BRL-CAD, el uso básico de las principales herramientas, el modelado, la importación/exportación, el análisis y la renderización.
A continuación, se incluyen breves introducciones sobre cómo abordaré cada parte de la documentación.
- Instalación básica: Agregaré un instructivo paso a paso para instalar el software BRL-CAD junto con las capturas de pantalla necesarias. El instructivo para principiantes es un buen punto de partida para los usuarios nuevos. Faltan algunos elementos, como los siguientes:
- Los pasos de este instructivo para principiantes no están numerados ni tienen viñetas. Tener un instructivo paso a paso con una captura de pantalla al final de cada paso aumenta las probabilidades de que el usuario se enganche con el instructivo.
- Una descripción general de las capacidades: Esta sección contendrá todas las áreas en las que BRL-CAD puede mostrar maravillas. Un enfoque diagramativo será una mejor manera de captar la atención hacia esta parte.
- Principios de modelado de BRL-CAD: Esta parte requerirá más explicaciones, ya que el usuario puede comprender mejor BRL-CAD una vez que tenga un conocimiento sólido de estos principios de modelado.
- Uso básico de las herramientas principales: En esta sección, tendremos instructivos independientes de las herramientas principales 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.
- Renderización: Abordaremos los conceptos básicos de la renderización y sus necesidades en nuestro software. Los usuarios también aprenderán a renderizar imágenes en BRL-CAD.
Además, se enfoca en los siguientes puntos:
- Al comienzo de la documentación, tendrás una comprensión básica de lo que trata este software.
- Cómo pueden conectarse los usuarios con esta comunidad de código abierto; vínculo al chat de Zulip de BRL-CAD
- En un nivel abstracto, hacer que la documentación sea un poco humorística y pedirles a los usuarios nuevos que no se desanimen por las palabras difíciles. Me gustó el enfoque empático que se usa en la página principal de la wiki de BRL-CAD.
- Tendrá capturas de pantalla de algunas funciones increíbles que los usuarios pueden hacer con este software.
Logros
Julio (período de revisión de propuestas)
- A medida que recorro los tutoriales existentes, me familiarizaré más con el software y sus documentos wiki.
- Haré mejoras en los documentos existentes.
Del 1 al 7 de agosto (vinculación con la comunidad)
- Debatir con los mentores sobre el proyecto.
- Perfeccionar los detalles del proyecto.
- Realiza los cambios necesarios en los eventos importantes (si es necesario).
Del 8 al 14 de agosto
- Familiarízate con Docbook XML
Del 15 al 21 de agosto
- Redacción de documentación para “Introducción básica a BRL-CAD”
- Escribe un instructivo paso a paso para la “Instalación básica”
Del 22 al 27 de agosto
- Explorar varias funciones de BRL-CAD y enumerarlas junto con capturas de pantalla
- Explica las funciones individuales en una página independiente.
Del 28 de agosto al 3 de septiembre
- Sigue trabajando en documentos individuales para ver las funciones.
Del 4 al 10 de septiembre
- Trabajar en los principios del modelado.
- Explicación de todos los principios de modelado
Del 11 al 17 de septiembre
- Trabaja en el uso básico de las principales herramientas.
- Haz una lista de las 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 el modelado para crear un modelo sólido para el instructivo y escribe un borrador junto con él.
Del 2 al 8 de octubre
- Mejora el borrador del modelado.
Del 2 al 8 de octubre
- Estudiar convertidores de importación y exportación
Del 9 al 15 de octubre
- Prepara documentos de importación y exportación.
- Comienza a trabajar en la renderización.
Del 16 al 22 de octubre
- Cómo documentar 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 los mentores y a otros miembros de la comunidad, y trabaja en los cambios.
- Dialogar con los mentores y hacer los cambios finales
Del 12 al 22 de noviembre
- Analizar y cambiar el proceso.
- Dar el último toque a la documentación.
Acerca de mí
Me gusta escribir desde mis días de estudiante. Llegaba a casa de la escuela y escribía sobre mi día, qué hacía que mi día fuera mejor o peor. Siempre quise anotar los errores que cometí y cómo puedo mejorarlos.
Durante mi capacitación como diseñador web, se nos pidió que escribiéramos lo que aprendíamos a diario. Documentaría algunos de los problemas que tuve y la solución a ellos.
Como persona, siempre hago todo lo posible para ayudar a los demás. Durante los días en la escuela y la universidad, les explicaba algunos temas a mis amigos después de entenderlos yo mismo. Participar en GSoD es un paso estupendo a través del cual, como escritor, puedo contribuir a que esta comunidad de código abierto sea más atractiva y útil para los usuarios nuevos de todo el mundo.