Projeto BRL-CAD

Esta página contém os detalhes de um projeto de escrita 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
Nome do projeto:
Um guia para iniciantes sobre o BRL-CAD
Duração do projeto:
Duração padrão (3 meses)

Project description

Guia para iniciantes do BRL-CAD

Resumo do projeto

O objetivo deste projeto é criar documentações dedicadas a usuários novos no BRL-CAD e código aberto.

Por que este projeto

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

Metas

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

Para isso, vou:

  • Mantenha a pontuação de Flesch-Kincaid do documento pelo menos acima de 50. De acordo com o método de Flesch-Kincaid, quanto maior a pontuação, mais fácil a peça será entender. É possível 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 parágrafos longos.
  • Use parágrafos e frases mais curtos porque isso exige um esforço mental comparativamente maior para ler e entender frases mais longas.
  • Use subtítulos para dividir o texto. Documentação bem estruturada: uma documentação bem estruturada desempenha um papel crucial na orientação de novos usuários. Isso evita que eles se percam, além de mostrar a eles aonde estão indo e o que estão fazendo. Para isso, criei um mapa mental básico que pode nos ajudar a documentar este guia para iniciantes de maneira organizada.

Descrição do projeto

Este projeto se concentra em escrever documentação para que novos usuários tenham acesso a esse software.

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

Introdução básica: o BRL-CAD (pronuncia-se be-are-el-cad) é um design assistido por computador (CAD, na sigla em inglês) de modelagem sólida construtiva de geometria sólida (CSG, na sigla em inglês). É um sistema avançado de modelagem sólida, multiplataforma e de código aberto, para design 3D assistido por computador e visualização gráfica. Não consegue lidar com isso? Vamos explicar isso melhor. Código aberto: software com código-fonte que qualquer pessoa pode inspecionar, modificar e aprimorar. Como o BRL-CAD é 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 sólido de modelagem: o BRL-CAD foca 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 e descrever totalmente o espaço 3D. Ela simula um objeto interna e externamente. Geometria sólida construtiva (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 no 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, os princípios de modelagem da BRL-CAD, uso básico das principais ferramentas, modelagem, importação/exportação, análise e renderização.

Abaixo estão listadas as breves introduções de como vou abordar 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. Alguns dos itens que acho que estão faltando são:
  • As etapas deste tutorial para iniciantes não estão indicadas por 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 conterá todas as áreas em que o BRL-CAD tem o poder de mostrar maravilhas. Uma abordagem diagrama será uma maneira melhor de chamar a atenção para essa parte.
  • Princípios de modelagem do BRL-CAD: esta parte exige mais explicações, porque o usuário pode entender melhor o BRL-CAD assim que tiver uma compreensão sólida desses princípios de modelagem.
  • Uso básico das principais ferramentas: nesse módulo, teremos tutoriais separados sobre as principais ferramentas e o uso básico delas. São tutoriais passo a passo.
  • Exportar/Importar: os usuários vão conhecer a Biblioteca de conversão de geometria. Um dos usos mais comuns do BRL-CAD é para converter a geometria de um formato para outro. Nesta seção, vamos discutir 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:

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

Marcos

Julho (período de revisão da proposta)

  • Vou me familiarizar mais com o software e seus documentos wiki conforme os tutoriais existentes.
  • Vou fazer melhorias nos documentos atuais.

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

  • Conversar com mentores sobre o projeto.
  • Aperfeiçoando os detalhes do projeto.
  • Faça as mudanças necessárias nos marcos (se necessário).

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 o tutorial passo a passo para a "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 funcionalidades.

4 a 10 de setembro

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

11 a 17 de setembro

  • Trabalhe no uso básico das principais ferramentas.
  • Crie uma lista selecionada 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 a 8 de outubro

  • Melhore o rascunho da modelagem.

2 a 8 de outubro

  • Estudar 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 escola. Eu chegava em casa da escola e escrevia sobre meu dia inteiro; o que tornava meu dia melhor ou pior. Sempre quis escrever 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 faço o meu melhor para ajudar os outros. Durante a faculdade e os dias da faculdade, eu explicaria alguns tópicos para meus amigos depois de entender esses tópicos 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 de todo o mundo.