Getting Started

Este guia acompanha todo o processo para contribuir com o Vidya Docs, desde a preparação do computador até a criação, validação e envio da primeira documentação.

Ao terminar, você terá:

• o projeto instalado e executando localmente;
• acesso à documentação no navegador;
• uma branch de trabalho criada;
• um novo arquivo Markdown na área correta;
• imagens e links funcionando;
• o build de produção validado;
• um commit pronto para Pull Request.

Antes de começar

O Vidya Docs é uma documentação interna. Você precisa ter acesso ao repositório da organização e solicitar a senha do site a uma pessoa autorizada da equipe.

1. Pré-requisitos

Instale ou solicite acesso às ferramentas abaixo.

Requisito	Versão ou condição	Finalidade
Git	Versão recente	Clonar o repositório e versionar alterações
Node.js	18 ou superior	Executar o Docusaurus
npm	Incluído no Node.js	Instalar dependências e executar scripts
GitHub	Acesso à organização conceito-sankhya	Clonar, enviar branches e abrir PRs
Editor	VS Code, Cursor ou equivalente	Editar Markdown e código
Senha do Vidya Docs	Fornecida pela equipe	Acessar o site local e publicado

1.1. Verificar as instalações

Abra um terminal e execute:

git --version
node --version
npm --version

O comando node --version deve retornar a versão 18 ou superior. Se algum comando não existir, instale a ferramenta correspondente antes de continuar.

Use a versão suportada

Versões antigas do Node.js podem causar erros durante a instalação ou o build. O projeto e os workflows de publicação usam Node.js 18 como referência.

2. Configurar o acesso ao GitHub

O repositório pode ser clonado por SSH ou HTTPS.

Opção A — SSH

Use esta opção se sua chave SSH já estiver cadastrada no GitHub:

git clone git@github.com:conceito-sankhya/vidya-docs.git

Para testar sua autenticação SSH:

ssh -T git@github.com

Opção B — HTTPS

Use HTTPS quando sua equipe trabalhar com autenticação pelo navegador ou token:

git clone https://github.com/conceito-sankhya/vidya-docs.git

Se o GitHub responder com erro de permissão, confirme se sua conta possui acesso ao repositório privado e se a autenticação está configurada.

3. Entrar no projeto

Depois de clonar:

cd vidya-docs

Confirme que está no diretório correto:

git status

O terminal deve mostrar o estado do repositório e a branch atual, sem informar que o diretório não é um repositório Git.

4. Instalar as dependências

O repositório possui package-lock.json. Para reproduzir exatamente as versões aprovadas pelo projeto, execute:

npm ci

Use npm ci na instalação inicial, nos pipelines e sempre que quiser uma instalação limpa. Use npm install apenas quando for necessário adicionar ou atualizar dependências, pois esse comando pode alterar o package-lock.json.

Ao finalizar, a pasta node_modules será criada. Ela é local e não deve ser adicionada ao Git.

5. Executar o projeto localmente

Inicie o servidor de desenvolvimento:

npm run start

Quando a compilação terminar, acesse:

http://localhost:3000/vidya-docs/

Informe a senha interna fornecida pela equipe. A sessão permanece válida por até 24 horas neste navegador ou até usar Encerrar sessão.

O servidor possui atualização automática: ao salvar um arquivo, a página normalmente é recompilada sem reiniciar o comando.

Usar outra porta

Se a porta 3000 estiver ocupada:

npm run start -- --port 3001

Nesse caso, abra http://localhost:3001/vidya-docs/.

Para encerrar o servidor, volte ao terminal e pressione Ctrl + C.

6. Conhecer a estrutura do projeto

Os diretórios mais importantes são:

vidya-docs/
├── docs/                  # Documentações em Markdown e MDX
│   ├── force-web/
│   ├── force-mobile/
│   ├── force-mobile-v2/
│   ├── sales-web/
│   ├── promoter/
│   ├── rocket/
│   ├── manager/
│   ├── communication-server/
│   ├── deploy/
│   └── tutoriais/
├── static/img/            # Imagens e outros arquivos estáticos
├── src/                   # Componentes e estilos do portal
├── sidebars.ts            # Organização principal do sidebar
├── docusaurus.config.ts   # Configuração do site
├── package.json           # Scripts e dependências
└── package-lock.json      # Versões exatas das dependências

Como o sidebar funciona

• Documentos colocados nas pastas de projetos já cadastradas são descobertos automaticamente.
• A ordem dos documentos pode ser controlada por sidebar_position no frontmatter.
• Uma nova subpasta pode usar _category_.json para definir nome, posição e página de índice.
• Documentos criados diretamente na raiz de docs/ precisam ser adicionados manualmente ao sidebars.ts.
• Não altere o sidebar se estiver apenas adicionando um documento a uma categoria já existente.

7. Atualizar a branch base

Antes de começar, atualize a branch principal:

git switch main
git pull --ff-only origin main

Crie uma branch para sua documentação seguindo o padrão do projeto:

git switch -c feat/ABC-123-adicionar-documentacao

Substitua ABC-123 pela chave real do ticket e use uma descrição curta em kebab-case.

8. Escolher onde a documentação será criada

Escolha a pasta pelo projeto ou assunto documentado.

Conteúdo	Pasta recomendada
Force Web	docs/force-web/
Force Mobile	docs/force-mobile/
Force Mobile v2	docs/force-mobile-v2/
Sales Web	docs/sales-web/
Promoter	docs/promoter/
Rocket	docs/rocket/
Manager	docs/manager/
Communication Server	docs/communication-server/
Deploy e CI/CD	docs/deploy/
Tutorial genérico	docs/tutoriais/
Página principal independente	docs/ e registro no sidebars.ts

Para customizações de clientes, mantenha o agrupamento existente. Exemplo:

docs/force-web/customizacoes-clientes/nome-do-cliente/

Regra prática

Coloque a documentação junto das outras páginas do mesmo produto, fluxo ou cliente. Antes de criar uma pasta nova, procure uma categoria equivalente em docs/.

9. Criar a primeira documentação

Neste exemplo, criaremos:

docs/force-web/minha-primeira-documentacao.md

Use nomes de arquivos em minúsculas e kebab-case:

minha-primeira-documentacao.md

Evite espaços, acentos, caracteres especiais e nomes genéricos como documento.md.

9.1. Adicionar o frontmatter

Todo documento deve começar com metadados entre ---:

---
sidebar_position: 99
title: Minha Primeira Documentação
description: Explica o objetivo, o fluxo e a validação da funcionalidade.
---

Campos recomendados:

Campo	Obrigatório	Uso
title	Sim	Nome exibido na aba, busca e sidebar
description	Recomendado	Resumo usado nos metadados e resultados
sidebar_position	Opcional	Ordem dentro da categoria
slug	Opcional	URL personalizada; use somente quando necessário

9.2. Usar uma estrutura completa

Copie o exemplo abaixo e substitua os dados fictícios pelos dados reais:

---
sidebar_position: 99
title: Minha Primeira Documentação
description: Descreve o funcionamento e a validação da funcionalidade ABC-123.
---

# Minha Primeira Documentação

> **Ticket:** [ABC-123](https://vidyacode.atlassian.net/browse/ABC-123)
>
> **Última atualização:** 19 de agosto de 2026

## Visão geral

Explique o problema resolvido, quem utiliza a funcionalidade e qual resultado é esperado.

## Pré-requisitos

- Permissão necessária para acessar a funcionalidade.
- Parâmetro ou configuração que precisa estar habilitado.
- Dados mínimos necessários para executar o fluxo.

## Fluxo funcional

1. O usuário acessa a tela.
2. Informa ou seleciona os dados necessários.
3. O sistema valida as informações.
4. A operação é concluída e o resultado é apresentado.

## Regras de negócio

| Regra | Comportamento                                    |
| ----- | ------------------------------------------------ |
| RN01  | Descreva a primeira regra com objetividade       |
| RN02  | Informe condições, exceções e resultado esperado |

## Arquivos envolvidos

| Arquivo                            | Responsabilidade                 |
| ---------------------------------- | -------------------------------- |
| `src/components/Example/index.tsx` | Interface e interação do usuário |
| `src/services/example.service.ts`  | Comunicação com o serviço        |
| `src/types/example.types.ts`       | Tipos usados pela funcionalidade |

## Implementação

Explique as decisões importantes. Inclua somente trechos pequenos e relevantes:

```ts
export function isValid(value: string): boolean {
  return value.trim().length > 0;
}
```

## Como validar

1. Inicie o projeto relacionado.
2. Acesse a funcionalidade documentada.
3. Execute o cenário principal.
4. Confirme o resultado esperado.
5. Repita usando pelo menos um cenário de erro ou exceção.

## Cenários de teste

| Cenário           | Entrada              | Resultado esperado              |
| ----------------- | -------------------- | ------------------------------- |
| Fluxo principal   | Dados válidos        | Operação concluída              |
| Campo obrigatório | Campo vazio          | Mensagem de validação exibida   |
| Falha do serviço  | Serviço indisponível | Erro tratado sem perda de dados |

## Limitações e observações

- Liste limitações conhecidas.
- Registre dependências externas.
- Informe impactos em outras áreas.

9.3. O que não pode faltar

Antes de considerar o conteúdo pronto, confirme se ele responde:

1. O que a funcionalidade faz?
2. Por que ela existe?
3. Quem ou qual sistema a utiliza?
4. Quais são os pré-requisitos?
5. Qual é o fluxo principal?
6. Quais regras e exceções existem?
7. Quais arquivos participam da implementação?
8. Como testar e validar?
9. Existem limitações, permissões ou riscos?
10. Qual ticket originou a mudança?

10. Adicionar imagens

Salve as imagens fora de docs/, dentro de static/img/.

Exemplo de estrutura:

static/img/force-web/minha-primeira-documentacao/
└── tela-principal.png

Referencie a imagem no Markdown a partir de /img/:

![Tela principal da funcionalidade](/img/force-web/minha-primeira-documentacao/tela-principal.png)

Boas práticas:

• use nomes descritivos e em kebab-case;
• recorte áreas que não ajudam na explicação;
• remova senhas, tokens, dados pessoais e informações de clientes;
• inclua um texto alternativo que explique o conteúdo da imagem;
• prefira PNG para telas e SVG para diagramas ou ícones vetoriais.

11. Adicionar links

Link para outro documento do projeto

Ao editar um documento dentro de docs/, prefira links relativos para arquivos Markdown:

[Processo de Documentação](../processo-documentacao.md)

Ajuste a quantidade de ../ conforme a pasta do arquivo atual.

Link externo

Use o endereço HTTPS completo:

[Abrir ticket](https://vidyacode.atlassian.net/browse/ABC-123)

Depois, clique em todos os links durante a revisão local.

12. Adicionar diagramas Mermaid

O projeto possui suporte a Mermaid. Use diagramas quando um fluxo for difícil de entender somente com texto:

```mermaid
flowchart LR
    A[Usuário inicia o fluxo] --> B{Dados válidos?}
    B -->|Sim| C[Concluir operação]
    B -->|Não| D[Exibir validação]
```

Mantenha rótulos curtos e valide o diagrama no navegador.

13. Gerar a documentação com IA

A IA pode criar uma primeira versão, mas não substitui a revisão técnica.

Processo recomendado

1. Abra o repositório do produto que foi alterado.
2. Forneça como contexto os arquivos modificados e o diff do ticket.
3. Informe o link do ticket e o título da funcionalidade.
4. Solicite a criação de um arquivo Markdown na pasta correta do Vidya Docs.
5. Exija fluxo, regras de negócio, arquivos envolvidos, validação e limitações.
6. Revise cada afirmação comparando com o código real.
7. Remova informações sensíveis antes de salvar.

Exemplo de prompt:

Crie uma documentação técnica em Markdown para a alteração abaixo.

Ticket: ABC-123
Título: Nome da funcionalidade
Destino: docs/force-web/nome-da-funcionalidade.md

Analise somente os arquivos fornecidos como contexto. Inclua:
- visão geral e objetivo;
- pré-requisitos e permissões;
- fluxo funcional completo;
- regras de negócio e exceções;
- tabela de arquivos envolvidos;
- pequenos trechos de código quando necessários;
- passos de validação e cenários de teste;
- limitações e impactos conhecidos.

Não invente comportamentos. Sinalize qualquer informação que não puder ser confirmada no código.

Consulte também o tutorial Gerar Documentação.

14. Conferir a documentação no navegador

Com npm run start em execução:

1. abra o projeto no navegador;
2. encontre o documento no sidebar;
3. confira título, hierarquia e espaçamentos;
4. teste o modo claro e o modo escuro;
5. reduza a largura da janela para verificar o mobile;
6. confira tabelas, imagens, diagramas e blocos de código;
7. clique em todos os links;
8. confirme que não há conteúdo cortado ou rolagem horizontal desnecessária.

Se o documento não aparecer, confirme:

• se o arquivo está dentro de uma pasta cadastrada no sidebars.ts;
• se a extensão é .md ou .mdx;
• se o frontmatter foi fechado com ---;
• se não existe outro documento com o mesmo slug ou ID;
• se o terminal mostra algum erro de compilação.

15. Executar as validações obrigatórias

Antes do commit, encerre erros de conteúdo e execute:

Verificação de tipos

npm run typecheck

Build de produção

npm run build

O build deve terminar com a mensagem de sucesso. Avisos de links ou âncoras quebradas devem ser investigados; não presuma que podem ser ignorados.

Conferir espaços e conflitos de formatação

git diff --check

Esse comando não deve imprimir erros.

Testar o build gerado

Opcionalmente, execute:

npm run serve

Isso serve o conteúdo estático da pasta build, aproximando o teste do ambiente publicado.

16. Revisar as alterações antes do commit

Confira os arquivos modificados:

git status
git diff

Não adicione ao commit:

• node_modules/;
• build/;
• .docusaurus/;
• arquivos temporários do editor;
• credenciais, tokens ou variáveis privadas;
• imagens que contenham informações sensíveis.

17. Criar o commit

Adicione somente os arquivos relacionados ao ticket:

git add docs/force-web/minha-primeira-documentacao.md
git add static/img/force-web/minha-primeira-documentacao/

Se não houver imagens, ignore o segundo comando.

Crie o commit no padrão do projeto:

git commit -m "docs(ABC-123): adicionar primeira documentacao"

Use a chave real do ticket e uma descrição objetiva.

18. Enviar a branch

git push -u origin feat/ABC-123-adicionar-documentacao

Depois do primeiro push, novos commits na mesma branch podem ser enviados apenas com:

git push

19. Abrir o Pull Request

No GitHub:

1. abra o repositório conceito-sankhya/vidya-docs;
2. selecione a branch enviada;
3. crie o Pull Request para a branch de destino definida pela equipe;
4. coloque a chave e o título do ticket no título do PR;
5. adicione o link do ticket na descrição;
6. informe qual projeto foi documentado;
7. descreva se a página é nova ou uma atualização;
8. anexe imagens da documentação renderizada quando houver mudança visual;
9. vincule o PR do Vidya Docs ao PR do projeto principal;
10. solicite a revisão do mesmo responsável pelo código da funcionalidade.

Checklist sugerido para a descrição:

## Resumo

- Documentação criada ou atualizada:
- Projeto relacionado:
- Ticket:

## Validações

- [ ] Conteúdo revisado com o código real
- [ ] Imagens e links conferidos
- [ ] Modo claro, escuro e mobile conferidos
- [ ] `npm run typecheck`
- [ ] `npm run build`
- [ ] `git diff --check`

## PR relacionado

- Link do PR da implementação:

20. Publicação

O site é publicado no GitHub Pages.

No fluxo atual:

• o workflow Manual Deploy pode ser executado manualmente por uma pessoa autorizada;
• o workflow Deploy on Version Change executa quando há alteração de versão no package.json enviada para main;
• o pipeline instala dependências com npm ci, executa o build e publica o conteúdo;
• não altere a versão do projeto somente para forçar uma publicação sem confirmar o processo com o responsável.

Depois do deploy, valide a página publicada em:

https://conceito-sankhya.github.io/vidya-docs/

Faça uma última conferência no ambiente publicado, especialmente em links, imagens, busca e navegação pelo sidebar.

21. Solução de problemas

node ou npm não foi encontrado

Instale o Node.js 18 ou superior, feche e abra o terminal e execute novamente node --version e npm --version.

npm ci falhou

Confirme a versão do Node.js e se o package-lock.json está presente. Não apague ou recrie o lockfile sem entender a causa do erro.

A porta 3000 está ocupada

npm run start -- --port 3001

O site não atualizou depois de salvar

Verifique erros no terminal. Se necessário, pare o servidor, limpe os arquivos gerados e inicie novamente:

npm run clear
npm run start

O documento não aparece no sidebar

• confirme o caminho do arquivo;
• valide o frontmatter;
• confira se a pasta está incluída no sidebars.ts;
• para um documento na raiz, adicione seu ID manualmente ao sidebar;
• reinicie o servidor após alterar a estrutura de pastas.

A imagem não aparece

• confirme que ela está dentro de static/img/;
• use /img/... no Markdown;
• confira letras maiúsculas e minúsculas no nome do arquivo;
• não use o caminho local absoluto do seu computador.

O build informa link ou âncora quebrada

Abra a página indicada no erro e confirme se o destino e o título da seção existem. Âncoras são geradas a partir dos títulos e podem mudar quando o texto do título é alterado.

O Mermaid não renderiza

Confirme se o bloco usa mermaid após as três crases e se todos os nós, setas e delimitadores estão fechados corretamente.

O MDX apresenta erro de hidratação

Evite HTML inválido, como um <p> dentro de outro <p>. Em componentes JSX, use className no lugar de class e feche todas as tags.

22. Checklist de conclusão

Sua primeira documentação está pronta quando todos os itens abaixo estiverem concluídos:

• Ferramentas instaladas e versões conferidas
• Repositório clonado e dependências instaladas
• Site executando localmente
• Branch criada com a chave do ticket
• Arquivo salvo na categoria correta
• Frontmatter válido
• Objetivo, fluxo, regras e exceções documentados
• Arquivos envolvidos e passos de validação incluídos
• Imagens sem informações sensíveis
• Links, diagramas e blocos de código conferidos
• Página validada em tema claro, escuro e mobile
• npm run typecheck concluído
• npm run build concluído
• git diff --check sem erros
• Commit no padrão do projeto
• Pull Request vinculado ao ticket e ao PR da implementação
• Revisão técnica solicitada
• Página publicada conferida após o deploy

Próximos passos

• Leia o Processo de Documentação para conhecer as responsabilidades e critérios de revisão.
• Use o tutorial Gerar Documentação para acelerar a primeira versão com IA.
• Use o tutorial Gerar Resolução de Ticket para resumir as alterações implementadas.