Guia de Estilo para Contribuições

Longevidade e Utilidade Prática

Para que o conteúdo seja realmente útil para equipes de todos os níveis de recursos e permaneça válido com o passar das temporadas, nosso foco não é ser superficial em muitos temas, mas sim ir a fundo nos fundamentos de engenharia subjacentes. Prós e contras dependem do contexto de cada jogo, mas os princípios da física e do design mecânico são universais.

Ao mesmo tempo, tecnologias pouco acessíveis ou raramente utilizadas pela maioria das equipes (como chassis usinados em bloco maciço - billet, ou transmissões omni exóticas) devem ser evitadas para não gerar confusão em iniciantes.

Por outro lado, detalhes práticos minuciosos que só são aprendidos na oficina (como envolver fita de silicone com fita isolante para evitar que descasque) são verdadeiros divisores de águas para as equipes.

Por que isso é essencial?

1. Não precisamos tomar as decisões pelos estudantes listando prós e contras fechados. Novos produtos e componentes COTS surgem a todo momento; capacitar os alunos com fundamentos sólidos permite que encontrem soluções criativas e únicas para a sua própria realidade.
2. Permite que os estudantes entendam por que determinada equipe tomou uma decisão e avaliem compensações de engenharia por conta própria.
3. Garante a longevidade do material. Quando o meta do jogo muda, reformular seções inteiras exige muito tempo. Se o guia for focado em fundamentos, ele permanecerá atual e valioso por muitos anos.
4. Os detalhes minuciosos de montagem representam a lacuna entre robôs confiáveis e robôs que falham em campo. Isso reduz drasticamente a sobrecarga de mentores de design e alavanca equipes sem mentores experientes.

Dicas para Escrever com Clareza:

1. Exemplifique com extremos: compare abordagens opostas para tornar o conceito evidente (ex: rodas stealth leves vs. volantes maciços de latão para inércia em shooters).
2. Analise aplicações consolidadas: identifique robôs de ponta que adotaram determinada solução e explique quais compromissos fundamentais nortearam aquela escolha.
3. Detalhes práticos de modelagem: nuances reais de CAD, como traçado de articulações de 4 barras ou posicionamento de tensionadores conforme a linha de carga, são de extremo valor didático.

Inspirado no Guia de Estilo do gm0

Evite falar em termos absolutos.

• “Apenas os Sith lidam com absolutos”
• Utilize listas de prós e contras para ponderar alternativas
• Explique sempre o porquê de algo ser vantajoso ou desvantajoso
  • Por exemplo, em vez de simplesmente dizer que pivôs com dead-axle são melhores que live-axle, explique: “Pivôs com dead-axle possuem maior momento de inércia de área na estrutura, pois o torque é transferido diretamente para as chapas externas. Com isso, o mecanismo torna-se muito mais resistente à torção e menos suscetível a empenamento ou quebra.”
  • Da mesma forma, em vez de apenas dizer que motores Kraken são ótimos, explique: “Recomendamos motores brushless de alto torque no drivetrain para melhorar a aceleração. Além disso, eles integram o controlador e possuem encoders de alta resolução que aumentam a precisão da odometria swerve. Lembre-se apenas de verificar a compatibilidade de eixos e módulos.”
• Enfatize que as equipes têm liberdade para inovar, mantendo expectativas realistas de execução.

O FRCDesign.org adota uma perspectiva competitiva e de alto rendimento.

• Não perca tempo recomendando soluções obsoletas ou ineficientes (ex: tração mecanum, que não possui tração nem força de empurrão frente a defesas no jogo moderno da FRC).
• Evite opiniões infundadas: aborde apenas tecnologias sobre as quais você possua experiência e conhecimento prático comprovado.
• Lembre-se de que tendências na FRC são dinâmicas: o fato de um mecanismo ter sido popular em um ano não significa que seja a melhor resposta para todos os jogos.

Cards para Redes Sociais (Social Cards)

As imagens de pré-visualização compartilhadas em plataformas como Discord são geradas automaticamente a partir do title e description de cada página.

Páginas de exemplos de mecanismos podem declarar uma propriedade image no frontmatter para utilizar o layout visual característico em verde:

---
title: Shooter da Equipe 1678 na Rapid React
description: Shooter de bolas com capô acionado por cremalheira
image: ./img/1678_2022_shooter.webp
---

Termos do Glossário

Os termos automáticos residem em src/data/glossary.ts. Ao adicionar um novo conceito técnico, sigla ou jargão de FRC:

1. Adicione o objeto na seção correspondente do array glossaryTerms.
2. Mantenha o term exatamente com a grafia que os leitores encontrarão no texto (a correspondência não diferencia maiúsculas de minúsculas).
3. Escreva uma definition concisa e didática, idealmente de uma frase.
4. Execute npm run build para certificar-se de que não houve erros de sintaxe.

A página completa do glossário visível em /resources/glossary/ é mantida em src/content/docs/resources/glossary.mdx. Se o novo termo deve constar nessa lista alfabética, atualize também esse arquivo.

Padrões de Marca da FIRST

• Respeite as diretrizes oficiais de uso de marca da FIRST®.
• Sempre grafe FIRST em maiúsculas e em itálico.
• Mantenha a grafia oficial dos nomes das equipes (consulte o The Blue Alliance em caso de dúvida).