Contribuindo para a Documentação do Frontend
A documentação é parte essencial do código-fonte do projeto Smart NX Frontend.
Ela garante que o conhecimento técnico seja compartilhado, rastreável e duradouro.
Este guia define como contribuir de forma padronizada para os documentos que vivem em /architecture, /processes, /contribution, /ux-guidelines e demais diretórios técnicos.
💡 A documentação é tratada como código: versionada, revisada e sujeita às mesmas boas práticas de qualidade.
Estrutura de Diretórios de Documentação
/architecture/ → Padrões e decisões técnicas (código, libs, arquitetura)
/processes/ → Fluxos de PR, branches, releases e QA
/contribution/ → Guias de contribuição e governança de docs
/ux-guidelines/ → Diretrizes de design system e UX
Cada documento deve possuir:
- Frontmatter YAML no topo (
title,description,tags) - Estrutura hierárquica clara com títulos (
#,##,###) - Histórico de versões no final (
🕓 Histórico de Versões)
1. Criação de Novo Documento
1.1. Estrutura base
Cada novo arquivo .md deve seguir o seguinte padrão:
---
title: Nome do Documento
description: Breve descrição do propósito.
tags: [tema1, tema2, tema3]
---
# Título Principal
Introdução curta (1–3 linhas) explicando o propósito do documento.
---
## 1. Seção Principal
Texto e exemplos.
---
## 🕓 Histórico de Versões
| Data | Versão | Autor / Revisor | Alterações |
|------|---------|----------------|-------------|
| dd/mm/aaaa | vX.X.X | Nome / Email | Descrição das mudanças |
✅ Use sempre Markdown puro, sem HTML embutido. ✅ Use linguagem técnica, objetiva e impessoal. ✅ Evite redundância — escreva o que agrega contexto real.
2. Fluxo de Contribuição
2.1. Criação de branch
As contribuições de documentação devem seguir o mesmo padrão de branches:
| Tipo | Prefixo | Exemplo |
|---|---|---|
| docs/ | Para qualquer nova documentação ou atualização | docs/NXS-2340-update-pr-guidelines |
Sempre derive sua branch de
develop.
2.2. Abrindo um Pull Request
-
Abra o PR com o prefixo
docs/e referência ao card Jira (quando aplicável). -
Não é necessário preencher descrição longa — apenas o título e o link Jira.
-
O PR deve ser aprovado por:
- 1 membro sênior, ou
- 2 membros da equipe.
Após merge, o documento é automaticamente versionado junto ao repositório.
3. Boas Práticas de Escrita
| Tema | Diretriz |
|---|---|
| Tom de voz | Técnico, direto, impessoal. Evite “você” — prefira “deve” ou “é recomendado”. |
| Clareza | Prefira frases curtas, listas e exemplos de código. |
| Consistência | Use a mesma terminologia adotada em outros docs (ex.: “branch pai”, “PR”, “task Jira”). |
| Formatação | Use títulos coerentes (##, ###), blocos de código e tabelas. |
| Versionamento | Sempre adicione uma entrada ao histórico (🕓 Histórico de Versões). |
| Linguagem | O idioma oficial é português técnico — termos de código permanecem em inglês. |
4. Tipos de Documentos Aceitos
| Tipo | Descrição | Diretório |
|---|---|---|
| Padrão técnico | Normas de código, dependências, libs, segurança. | /architecture |
| Processo interno | PRs, branches, releases, QA. | /processes |
| Contribuição | Guias de como contribuir, revisar, escrever docs. | /contribution |
| UI/UX | Padrões visuais, acessibilidade, comportamento. | /ux-guidelines |
5. Revisão de Documentos
A revisão segue o mesmo modelo dos PRs de código:
| Regra | Descrição |
|---|---|
| Revisores | 1 sênior ou 2 membros da equipe. |
| Branch Base | Sempre develop. |
| Checks Automáticos | Lint de Markdown e ortografia (quando aplicável). |
| Política de Merge | Squash and Merge. |
| Remoção de Branch | Após o merge, remover branch docs/. |
6. Ferramentas Recomendadas
- VSCode + Prettier: para manter formatação padronizada.
- MarkdownLint: validação automática de títulos e espaçamento.
- Mermaid.js: para diagramas (
graph TD,sequenceDiagrametc.). - Table Formatter: extensão útil para alinhar tabelas Markdown.
- Frontmatter Preview: ajuda a validar o cabeçalho YAML.
7. Dicas Avançadas
-
Sempre referencie outros documentos com links relativos:
Consulte [Padrões de Código](/architecture/code-standards.md) -
Use blocos de código com linguagem específica (
tsx,bash,jsonetc.). -
Inclua diagramas apenas quando simplificarem entendimento.
-
Prefira nomes descritivos e curtos para os arquivos (
auth-flow.md,color-system.md). -
Evite duplicação — se o conteúdo for complementar, linke, não replique.
🕓 Histórico de Versões
| Data | Versão | Autor / Revisor | Alterações |
|---|---|---|---|
| 29/10/2025 | v1.0.0 | @Matheus Telles | Criação inicial e estrutura base do documento |