Este documento estabelece o padrão oficial para criação de documentação técnica no fórum NCS. Seguindo estas diretrizes, garantimos consistência, clareza e facilidade de compreensão em todos os materiais técnicos.
Para melhor entendimento das diretrizes, é importante que cada autor de documentação siga rigorosamente os padrões estabelecidos, gerando uniformidade e profissionalismo em todo o conteúdo técnico da empresa.
Este próprio documento serve como exemplo prático da aplicação dos padrões definidos.
Toda documentação técnica deve conter os elementos abaixo em ordem específica.
Estabelecimento do contexto e objetivo do documento
Título Principal: Deve usar formatação H1 personalizada com data-ncslogo2
Subtítulo: Usar formatação H3 com data-textdest para descrição resumida
Introdução: Explicar:
- O que é o tópico abordado
- Por que é importante
- Como este documento ajuda
- Escopo do conteúdo
Representação visual do processo ou estrutura
Fluxograma: Quando aplicável, incluir diagrama visual que mostre:
- Etapas do processo
- Fluxo de decisões
- Responsabilidades
- Pontos de controle
Visão Geral: Para tópicos não-processuais:
- Diagrama de arquitetura
- Mapa conceitual
- Estrutura hierárquica
- Relacionamentos entre componentes
Formato: Imagens em alta resolução com descrições claras
Informações técnicas organizadas em seções expansíveis
Organização por Passos: Para processos sequenciais:
- Numeração clara (Passo 1, Passo 2, etc.)
- Responsável identificado entre colchetes [Função]
- Título descritivo de cada etapa
Seções Expansíveis: Usar <details> e <summary> para:
- Manter foco no essencial
- Permitir navegação rápida
- Facilitar consultas específicas
Screenshots: Incluir imagens para cada ação:
- Telas do sistema
- Campos destacados
- Resultados esperados
Formatação de Instruções:
- Campos obrigatórios: Negrito
- Valores específicos: Itálico
-
Códigos e comandos: Código - Botões e ações: Negrito
Informações importantes, dicas e alertas
Tipos de Destaque:
Quando Usar:
- Informações que podem causar erros
- Dicas para otimizar processos
- Pré-requisitos importantes
- Consequências de ações
Hierarquia de Títulos:
- H1: Título principal do documento
- H2: Seções principais
- H3: Subseções
- H4: Detalhes específicos
Listas:
- Numeradas: Para sequências e processos
- Com marcadores: Para itens sem ordem específica
- Definições: Para glossários e explicações
Imagens:
- Resolução mínima: 1200px largura
- Formato: PNG para telas, JPG para fotos
- Descrição alternativa sempre presente
- Tamanho otimizado para web
Links:
- Sempre descriptivos (evitar “clique aqui”)
- Abrir em nova aba quando apropriado
- Verificar funcionamento antes de publicar
Checklist de Publicação:
- [ ] Título claro e descritivo
- [ ] Introdução contextualizada
- [ ] Estrutura lógica seguida
- [ ] Screenshots atualizadas
- [ ] Formatação consistente
- [ ] Revisão ortográfica
- [ ] Teste de todos os links
- [ ] Validação técnica
Este documento estabelece o padrão oficial de documentação técnica da NCS. Sua aplicação consistente garante qualidade e uniformidade em todo o conteúdo técnico da empresa.