Projeto BRL-CAD

Esta página contém os detalhes de um projeto de redação técnica aceito para a temporada de documentos do Google.

Resumo do projeto

Organização de código aberto:
BRL-CAD
Redator técnico:
sahibkaur
(link em inglês)
Nome do projeto:
Um guia para iniciantes sobre BRL-CAD
Duração do projeto:
Duração padrão (3 meses)

Project description

Guia para iniciantes do BRL-CAD

Resumo do projeto

Este projeto visa criar documentação dedicada a usuários que não são apenas novos no BRL-CAD, mas também novos no código aberto.

Por que este projeto

Quando visitei o site do BRL-CAD pela primeira vez, como eu era iniciante em código aberto e BRL-CAD, fiquei surpreso com a quantidade de informações de uma só vez. Mas, no fundo, sabia que havia muito para aprender aqui. Então, eu queria criar uma documentação para que novos usuários como eu aproveitassem muito essa comunidade e se sentem à vontade para começar.

Objetivos

Este projeto segmentará novos usuários. Estes são alguns dos pontos que minha documentação visa alcançar: Para garantir que novos usuários se sintam à vontade: Como esta documentação é para novos usuários não apenas novos no BRL-CAD, mas também novos no código aberto.

Para isso, vou:

  • Certifique-se de manter a pontuação Flesch-Kincaid do documento no mínimo acima de 50. De acordo com o método de Flesch-Kincaid, quanto maior a pontuação, mais fácil a peça é entender. Você pode verificar a pontuação de legibilidade on-line.
  • Use listas numeradas ou com marcadores para que os leitores não fiquem entediados ou distraídos com longos parágrafos.
  • Use parágrafos e frases mais curtos porque isso exige menos trabalho mental para ler e entender frases mais longas.
  • Use subtítulos para quebrar o texto. Documentação bem estruturada: uma documentação bem estruturada desempenha um papel crucial na orientação dos novos usuários. Isso evita que eles se percam e que eles saibam para onde estão indo e o que estão fazendo. Para conseguir isso, criei um mapa mental que pode nos ajudar a documentar este guia para iniciantes de forma organizada.

Descrição do projeto

Este projeto se concentra na escrita de documentação para novos usuários colocarem as mãos neste software.

Confira abaixo um exemplo de como pretendo deixar a documentação mais descritiva.

Introdução básica: BRL-CAD (pronuncia-se be-are-el-cad) é um design assistido por computador (CAD) de modelagem sólida construtiva de geometria sólida (CSG). É um poderoso sistema de modelagem sólida multiplataforma e de código aberto para design 3D computadorizado e visualização gráfica. Não consegue se enxergar? Vamos explicar isso melhor. Código aberto: são softwares com código-fonte que qualquer pessoa pode inspecionar, modificar e aprimorar. Por ser um software de código aberto, você pode contribuir e tornar o BRL-CAD melhor do que antes. Design assistido por computador (CAD): em palavras simples, CAD é o uso de programas de computador para criar representação gráfica bidimensional de objetos físicos. Sistema de modelagem sólido: o BRL-CAD se concentra na modelagem sólida do CAD. A modelagem sólida se distingue de outras formas de modelagem geométrica pela ênfase em ser fisicamente precisa, descrevendo totalmente o espaço 3D. Ele simula um objeto interna e externamente. Construive Solid Geometry (CSG): o CSG permite representar modelos complexos como uma série de operações booleanas entre primitivos. Os objetos sólidos mais simples usados para a representação são chamados de primitivos. Para entender o CSG em um nível básico, acesse este link.

*Como mencionado na descrição da ideia do projeto: A documentação abordará, no mínimo, a instalação básica, uma descrição geral dos recursos, dos princípios de modelagem da BRL-CAD, uso básico das principais ferramentas, modelagem, importação/exportação, análise e renderização.

Abaixo há introduções breves sobre como vou cobrir cada parte da documentação.

  • Instalação básica: adicionarei um tutorial passo a passo para instalar o software BRL-CAD com as capturas de tela necessárias. O tutorial para iniciantes é um bom lugar para os novos usuários começarem. Acho que faltam algumas coisas:
  • As etapas deste tutorial para iniciantes não são indicadas com marcadores nem numeradas. Ter um tutorial passo a passo com uma captura de tela ao final de cada etapa aumenta a probabilidade do usuário se prender a ele.
  • Uma descrição geral das capacidades: esta seção apresentará todas as áreas em que o BRL-CAD tem o poder de mostrar maravilhas. Uma abordagem diagramada será uma maneira melhor de chamar a atenção para essa parte.
  • Princípios de modelagem do BRL-CAD: esta parte exigirá mais explicações porque o usuário pode entender melhor o BRL-CAD depois de ter uma compreensão sólida desses princípios de modelagem.
  • Uso básico das principais ferramentas: nessa seção, teremos tutoriais separados sobre as principais ferramentas e o uso básico delas. Esses serão tutoriais passo a passo.
  • Exportar/importar: os usuários poderão saber mais sobre a Biblioteca de conversão de geometria. Um dos usos mais comuns do BRL-CAD é a conversão de geometria de um formato para outro. Nesta seção, vamos discutir sobre os conversores de exportação e importação.
  • Renderização: vamos abordar os fundamentos da renderização e a necessidade dela em nosso software. Os usuários também vão saber como renderizar imagens em BRL-CAD.

Além disso, o foco também está nos seguintes pontos:

  • O início da documentação vai proporcionar um entendimento básico desse software.
  • Como os usuários podem se conectar com esta comunidade de código aberto: link para o chat zulip em BRL-CAD.
  • Em um nível abstrato, tornar a documentação um pouco engraçada e pedir aos novos usuários para não desanimarem com palavras pesadas. Gostei da abordagem empática usada na página principal da wiki da BRL-CAD.
  • Ele terá capturas de tela de algumas coisas incríveis que os usuários podem fazer usando esse software.

Metas

Julho (Período de Revisão da Proposta)

  • Vou me familiarizar mais com o software e seus documentos wiki durante os tutoriais existentes.
  • Farei melhorias nos documentos existentes.

1o a 7 de agosto (vínculo comunitário)

  • Discutir com mentores sobre o projeto.
  • Aperfeiçoando os detalhes do projeto.
  • Se necessário, faça as alterações necessárias nos marcos.

8 a 14 de agosto

  • Conheça o XML do Docbook

15 a 21 de agosto

  • Escrever documentação para “Introdução básica ao BRL-CAD”
  • Como escrever um tutorial passo a passo para “Instalação básica”

22 a 27 de agosto

  • Conheça os vários recursos do BRL-CAD e liste todos eles com capturas de tela.
  • Explicar recursos individuais em uma página separada.

28 de agosto a 3 de setembro

  • Continue trabalhando em documentos individuais para recursos.

4 a 10 de setembro

  • Trabalho com princípios de modelagem.
  • Explicação de todos os princípios de modelagem.

11 a 17 de setembro

  • Trabalhe no uso básico de ferramentas principais.
  • Crie uma lista de ideias para documentar o uso básico de cada ferramenta.

18 a 24 de setembro

  • Documentar o uso de cada ferramenta.

25 de setembro a 1o de outubro

  • Trabalhe na modelagem para criar um modelo sólido para o tutorial e escrever um rascunho junto.

2 de outubro a 8 de outubro

  • Melhore o rascunho da modelagem.

2 de outubro a 8 de outubro

  • Estudar os conversores de exportação e importação.

9 a 15 de outubro

  • Prepare a exportação e a importação de documentos.
  • Comece a trabalhar na renderização.

16 a 22 de outubro

  • Documentar o tutorial de renderização.

23 a 29 de outubro

  • Revisando todos os documentos.

30 de outubro a 5 de novembro

  • Como trabalhar no XML do Docbook

6 a 12 de novembro

  • Peça avaliações de mentores e outros membros da comunidade e trabalhe nas mudanças.
  • Conversar com os mentores e fazer as mudanças finais.

12 a 22 de novembro

  • Processo de discussão e mudanças.
  • Dar o toque final à documentação.

Sobre mim

Gosto de escrever desde os tempos de faculdade. Eu chegava em casa da escola e escrevia sobre o meu dia, o que tornou meu dia melhor ou pior. Sempre quis anotar os erros que cometi e como posso melhorá-los.

Durante meu treinamento como web designer, pedimos para que escrevíamos o que aprendemos diariamente. Eu documentaria alguns dos problemas que enfrentei e a solução para eles.

Como pessoa, sempre me esforço para ajudar os outros. Durante a escola e a faculdade, eu explicava alguns assuntos para meus amigos depois de entender esses assuntos sozinho. Participar do GSoD é um passo esplêndido pelo qual eu, como escritor, posso contribuir para tornar esta comunidade de código aberto mais envolvente e útil para novos usuários em todo o mundo.