Projeto BRL-CAD

Esta página contém os detalhes de um projeto de redação técnica aceito para a Google Season of Docs.

Resumo do projeto

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

Project description

Guia para iniciantes sobre o BRL-CAD

Resumo do projeto

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

Por que esse projeto?

Quando visitei o site do BRL-CAD pela primeira vez, como eu era nova no código aberto e no BRL-CAD, fiquei sobrecarregada com a quantidade de informações de uma só vez. Mas, no fundo, eu sabia que havia muito o que aprender. Então, quis criar uma documentação para novos usuários como eu para aproveitar ao máximo essa comunidade e me sentir à vontade para começar.

Metas

Este projeto vai segmentar novos usuários. Eis alguns pontos que minha documentação pretende atingir: Garantir que novos usuários se sintam à vontade: já que 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:

  • Mantenha a pontuação Flesch-Kincaid do documento acima de 50. De acordo com o método Flesch-Kincaid, quanto maior a pontuação, mais fácil é entender a peça. Você pode conferir a pontuação de legibilidade on-line.
  • Use listas com marcadores ou numeradas para que os leitores não se distraiam ou se distraiam com parágrafos longos.
  • Use parágrafos e frases mais curtos, porque ler e entender frases mais longas exige mais esforço mental.
  • Use subtítulos para quebrar o texto. Documentação bem estruturada: ela é essencial para orientar novos usuários. Isso evita que eles se percam e informa onde estão indo e o que estão fazendo. Para isso, criei um mapa mental aproximado que pode nos ajudar a documentar este guia para iniciantes de maneira organizada.

Descrição do projeto

O foco deste projeto é escrever documentações para que novos usuários conheçam esse software.

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

Introdução básica: BRL-CAD (pronuncia-se be-are-el-cad) é um design auxiliado por computador (CAD) de geometria sólida construtiva (CSG, na sigla em inglês). É um sistema de modelagem sólida de código aberto e multiplataforma para design assistido por computador 3D e visualização gráfica. Não consegue entender? Vamos explicar isso melhor. Código aberto: software de código aberto é um software com código-fonte que qualquer pessoa pode inspecionar, modificar e aprimorar. O BRL-CAD é um software de código aberto, e você pode contribuir para melhorar o BRL-CAD. Design auxiliado por computador (CAD): em palavras simples, o CAD é o uso de programas de computador para criar representações gráficas bi ou tridimensionais de objetos físicos. Sistema de modelagem sólida: o BRL-CAD se concentra na modelagem sólida CAD. A modelagem sólida se distingue de outras formas de modelagem geométrica por uma ênfase na precisão física, descrevendo totalmente o espaço 3D. Ele simula um objeto internamente 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 em um nível básico, acesse este link.

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

Alinhadas estão breves introduções sobre como abordarei cada parte da documentação.

  • Instalação básica: vou adicionar 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. Algumas coisas que faltam são:
  • As etapas deste tutorial para iniciantes não estão numeradas ou numeradas. Ter um tutorial detalhado com uma captura de tela no final de cada etapa aumenta a probabilidade de o usuário se interessar pelo tutorial.
  • Uma descrição geral dos recursos: Esta seção vai conter todas as áreas em que o BRL-CAD pode fazer maravilhas. Uma abordagem esquemática é uma maneira melhor de chamar a atenção para essa parte.
  • Princípios de modelagem de BRL-CAD: esta parte vai exigir mais explicações porque o usuário poderá entender melhor o BRL-CAD assim que tiver um entendimento sólido desses princípios de modelagem.
  • Uso básico das principais ferramentas: nesse tópico, vamos ter tutoriais separados das principais ferramentas e seu uso básico. Esses serão tutoriais detalhados.
  • Exportar/importar: os usuários conhecerão a Biblioteca de conversão de geometria. Um dos usos mais comuns do BRL-CAD é converter geometria de um formato para outro. Nesta seção, abordamos os conversores de exportação e importação.
  • Renderização: vamos abordar os conceitos básicos da renderização e a necessidade dela no nosso software. Os usuários também vão aprender a renderizar imagens em BRL-CAD.

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

  • O início da documentação terá uma compreensão básica do que é esse software.
  • Como os usuários podem se conectar com essa comunidade de código aberto; link para o chat do zulip em BRL-CAD.
  • Em um nível abstrato, tornar a documentação um pouco engraçada e pedir que os novos usuários não se desanimem com palavras pesadas. Gostei da abordagem empática usada na página principal da wiki do 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 análise da proposta)

  • Vou me familiarizar mais com o software e os documentos do wiki enquanto leio os tutoriais.
  • Faremos melhorias nos documentos existentes.

1 a 7 de agosto (vínculo com a comunidade)

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

8 a 14 de agosto

  • Conheça o Docbook XML

De 15 a 21 de agosto

  • Documentação de redação de “Introdução básica a BRL-CAD”
  • Como escrever um tutorial passo a passo para “Instalação básica”

22 a 27 de agosto

  • Explorando vários recursos de BRL-CAD e listando-os com capturas de tela.
  • Explique os recursos individuais em uma página separada.

28 de agosto a 3 de setembro

  • Continue trabalhando em documentos individuais para verificar os recursos.

4 a 10 de setembro

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

11 a 17 de setembro

  • Trabalhar com o uso básico das principais ferramentas.
  • Selecione ideias para documentar o uso básico de cada ferramenta.

De 18 a 24 de setembro

  • Documentar o uso de cada ferramenta.

25 de setembro a 1º de outubro

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

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 documentos de exportação e importação.
  • Comece a trabalhar na renderização.

De 16 a 22 de outubro

  • Documentar o tutorial de renderização.

23 a 29 de outubro

  • Analisando todos os documentos.

De 30 de outubro a 5 de novembro

  • Como trabalhar com o XML do Docbook

6 a 12 de novembro

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

12 a 22 de novembro

  • Discussão e processo de mudanças.
  • Dar os retoques finais na documentação.

Sobre mim

Eu gosto de escrever desde a escola. Eu voltava da escola e escrevia tudo sobre meu dia, o que o tornou melhor ou pior. Sempre gostei de anotar os erros que cometi e como posso melhorá-los.

Durante meu treinamento como designer da Web, tivemos que anotar o que aprendemos diariamente. Eu documentaria alguns dos problemas que enfrentei e a solução para eles.

Eu sempre faço o possível para ajudar os outros. Na escola e na faculdade, eu explicava alguns tópicos para meus amigos depois de entender os assuntos. Participar do GSoD é uma etapa incrível em que eu, como redatora, posso contribuir para tornar essa comunidade de código aberto mais envolvente e útil para novos usuários em todo o mundo.