Artigos de Documentação: Referência Versionada para Usuários Existentes

Um artigo de documentação é uma referência mantida para alguém que já usa um produto, API, serviço, dispositivo ou processo operacional. Ele responde a uma pergunta precisa de consulta — o que uma configuração faz, quais valores um campo aceita, qual acesso é necessário, qual versão se comporta de determinada maneira ou onde um limite se aplica — sem fazer o leitor passar primeiro por um argumento de marketing.

Seu contrato é escopo → pré-requisitos → comportamento atual → referência exata → exceções → tarefa relacionada. A página é bem-sucedida quando um usuário recupera o fato correto para a versão e função certas. Transformar todo rótulo de interface em uma URL pública não ajuda.

Perguntas que responde

A pergunta principal é: “O que esse comportamento do produto significa na minha versão e contexto?” Perguntas de apoio incluem:

• Esta página se aplica ao meu produto, plano, função, região, plataforma e versão?
• O que já deve ser verdade antes de eu usar este recurso ou consultar este campo?
• Quais são os valores aceitos, padrões, limites, formatos e efeitos colaterais?
• Qual comportamento é atual e o que mudou em relação a uma versão anterior?
• Qual exemplo demonstra a regra sem esconder condições importantes?
• O que devo ler em seguida se precisar de um procedimento, diagnóstico ou histórico de alterações?
• Esta informação é segura e útil na busca pública ou requer contexto autenticado?

Quando usar este tipo de post

Use documentação quando uma página estável precisar apoiar consultas repetidas. O assunto precisa de um responsável autoritativo, comportamento testável e um sinal de manutenção, como uma versão, API, plano ou mudança de interface.

Uma página chamada “Como configurar campos de exportação” ainda pode ser documentação quando seu valor duradouro é um catálogo de campos e os usuários saltam diretamente para parâmetros individuais. Por outro lado, “Exporte seu primeiro relatório” é um guia prático quando o leitor precisa seguir uma sequência e verificar um arquivo baixado. A gramática do título não decide o formato; a tarefa do leitor e o formato da resposta sim.

Melhor para estes tipos de negócio

1. SaaS. A melhor adequação porque funções, planos, configurações, integrações, APIs, modelos de dados e cadência de lançamentos produzem necessidades exatas de referência. A documentação deve distinguir comportamento de interface de comportamento de API e permissões de usuário de direitos de assinatura.
2. Ecommerce. Forte para administração de comerciantes, feeds de produtos, regras de pagamento, devoluções, integrações e uso pós-compra. Separe o help do cliente da documentação do comerciante para que um comprador não caia em uma referência de implementação.
3. Marketplaces. Forte onde comprador, vendedor, prestador e administrador veem estados diferentes. Cada artigo deve identificar o ator porque o mesmo rótulo pode expor controles ou obrigações distintas.
4. Agências. Útil para portais de clientes, padrões de entrega, fluxos de trabalho recorrentes e ferramentas compartilhadas. Publique referência reutilizável para clientes publicamente apenas quando não expuser controles internos, credenciais ou detalhes operacionais proprietários.
5. Serviços B2B. Útil para sistemas de onboarding, transferências de dados, especificações de arquivos, estados de aprovação e portais de serviço. Evite apresentar um compromisso contratual como um fato genérico de central de ajuda quando os termos variam por conta.
6. Fabricantes e indústrias. Valioso para controles, software, compatibilidade, configuração, registros de manutenção e parâmetros técnicos. Material crítico de segurança requer revisão controlada, aplicabilidade explícita de modelo e uma rota para o manual autoritativo.

Intenção de busca

Intenção de busca é o resultado que uma pessoa espera de uma consulta. A intenção de documentação é geralmente navegacional mais informacional: o usuário conhece o produto ou objeto e quer um fato exato, como “retenção de exportação Northstar”, “valores de status Northstar” ou “tamanho de página da API Northstar”. Marca, recurso, linguagem de tarefa livre de erros, versão e plataforma frequentemente aparecem juntos.

O resultado ideal abre próximo à resposta. Use cabeçalhos descritivos, âncoras estáveis, valores aceitos e qualificadores de versão. Uma afirmação extraída deve preservar sua condição: “Nos planos Team e Enterprise, exportações concluídas permanecem disponíveis por 30 dias.”

Documentação pública deve ranquear quando responde a uma pergunta duradoura sem revelar dados da conta: formatos suportados, campos públicos da API, compatibilidade, limites, significado de configuração e comportamento documentado.

Documentação não deve ranquear quando espelha um rótulo de interface, duplica uma página atual, cobre uma versão obsoleta sem necessidade contínua, expõe detalhes sensíveis ou precisa de contexto de conta privada. Use help autenticado, orientação no aplicativo, noindex, consolidação ou um estado de arquivamento claro. A demanda de busca nunca justifica publicar segredos ou caminhos de exploração.

Estrutura da página

As faixas de palavras são controles de produção, não cotas mínimas. Uma referência de campo estreita pode ser mais curta; uma referência de recurso versionado pode precisar de mais espaço porque aplicabilidade e exceções evitam erros custosos.

A maioria dos artigos de documentação substanciais fica entre 1.500 e 2.800 palavras. Adicione detalhes apenas onde eles evitam ambiguidade: escopo, pré-requisito, valor, padrão, efeito colateral, exceção ou mudança de versão.

Elementos obrigatórios

Leitores de referência escaneiam. Posicione as informações de aplicabilidade antes da referência para que um valor tecnicamente correto não seja aplicado ao plano ou versão errada.

Frontmatter

Siga a especificação de frontmatter. Nesta especificação de tipo de post, entity = "post-type-documentation-article". Em uma página de documentação produzida, use um valor estável de objeto de produto como northstar-scheduled-export-settings, não uma frase promocional como effortless-reporting e não um número de versão que forçaria uma nova identidade após cada lançamento.

Use schemaType = "Article". A marcação schema deve descrever a página visível; não selecione HowTo apenas porque um exemplo contém três ações. Adicione dados estruturados de FAQ apenas quando as perguntas e respostas visíveis corresponderem exatamente a eles. Referência de API ou semântica específica de software podem ser representadas em outro lugar no modelo de dados do site, mas um tipo de schema mais específico não deve ser inventado no frontmatter sem suporte de template.

Armazene os campos que o sistema de manutenção pode aplicar: área do produto, planos, função, plataforma, intervalo de versões, data de verificação, responsável e URL de substituição. lastmod significa que o comportamento foi revisado, não que um erro de digitação foi corrigido. Preserve a URL canônica entre versões compatíveis.

Exemplo completo

Este exemplo fictício de análise demonstra uma página de referência, não um procedimento completo de exportação.

# Configurações de exportação agendada

Exportações agendadas criam um arquivo CSV ou JSON a partir de um relatório salvo em um horário UTC fixo e o entregam a um destino aprovado. Estão disponíveis para Editores e Administradores nos planos Team e Enterprise. Esta referência se aplica ao aplicativo web Northstar Analytics 6.4 e foi verificada em 27 de agosto de 2026.

## Antes de usar esta referência

Você precisa de um relatório salvo existente, um destino habilitado e acesso de Editor ou Administrador. Um Visualizador pode baixar uma exportação existente, mas não pode criar ou alterar um agendamento. Administradores de destino podem impor limites adicionais de retenção ou tamanho de arquivo.

## Referência de configurações

| Configuração | Valor aceito | Padrão | Efeito e restrições |
|---|---|---|---|
| Nome | 1–80 caracteres | Nome do relatório | Identifica o agendamento; alterá-lo não renomeia arquivos anteriores. |
| Formato | `csv` ou `json` | `csv` | CSV usa a ordem de colunas visível do relatório. JSON usa chaves de campo estáveis. |
| Horário de execução | `HH:MM` em UTC | `08:00` | Mudanças de horário de verão não alteram o horário de execução UTC. |
| Incluir linhas vazias | Ativado ou desativado | Desativado | Disponível apenas para relatórios tabulares; ignorado para relatórios de resumo. |
| Retenção | 1–30 dias | 7 dias | Arquivos existentes expiram independentemente do agendamento que os criou. |

## Comportamento e limites

Um agendamento lê a configuração do relatório salvo quando a execução começa. Editar o relatório portanto altera arquivos futuros, mas não arquivos já gerados. Pausar um agendamento impede novas execuções; não exclui arquivos retidos. Excluir o destino desativa a entrega e coloca o agendamento em `Needs attention`.

## Exemplo

Para um CSV diário necessário às 09:00 em Bratislava durante o horário padrão, defina o horário de execução UTC para `08:00`. Revise o horário quando as regras de horário de verão mudarem, pois os agendamentos permanecem fixos em UTC.

Exemplo inválido: inserir `Europe/Bratislava` no campo de horário de execução. O campo aceita um horário UTC, não um identificador de fuso horário.

## Diferenças de versão

- Versão 6.4: Exportações JSON usam chaves de campo estáveis; o rótulo da coluna exibida não se torna mais a chave.
- Versões 6.1–6.3: Chaves JSON seguem os rótulos de coluna exibidos. Integrações existentes devem ser verificadas antes da atualização.
- Antes de 6.1: exportação JSON agendada não está disponível. Use CSV ou atualize para uma versão suportada.

## Se uma exportação não chegar

Não adicione correções especulativas aqui. Abra o guia de solução de problemas "A exportação agendada não chegou", que verifica o estado do agendamento, autorização do destino, limites de arquivo e incidentes de serviço em ordem de diagnóstico.

## Tarefas relacionadas

- Crie sua primeira exportação agendada — configuração ordenada e verificação de sucesso
- Solucione uma exportação agendada ausente — diagnóstico guiado por sintoma
- Notas de versão do Northstar Analytics 6.4 — mudanças de comportamento e nota de migração

## Registro de verificação

Verificado no aplicativo web 6.4 pelo responsável do produto Reporting em 27 de agosto de 2026. Revisar quando permissões, formatos, retenção, agendamento ou comportamento de destino mudarem.

Galeria de design

Use configurações, limites, funções e fatos de versão idênticos entre variantes para que a revisão de design meça a velocidade de recuperação em vez de diferenças de texto.

Checklist de qualidade

Um artigo de documentação está pronto apenas quando cada afirmação aplicável é verdadeira:

• A abertura nomeia o objeto exato e fornece o comportamento atual antes de contexto ou benefícios.
• A aplicabilidade de produto, plano, função, região, plataforma e versão é explícita onde alteram a resposta.
• Pré-requisitos aparecem antes de configurações ou exemplos que dependam deles.
• Cada termo técnico é definido no primeiro uso, expresso por meio de um rótulo de interface familiar ou vinculado à sua definição canônica.
• Campos, valores, padrões, unidades, formatos, limites e efeitos colaterais vêm de uma fonte autoritativa ou teste de produto verificado.
• Tabelas de referência usam dimensões consistentes; células vazias não escondem padrões ou exceções desconhecidos.
• Exemplos informam as condições que os tornam válidos e incluem um exemplo inválido ou limítrofe quando há probabilidade de confusão.
• Avisos aparecem antes de comportamento destrutivo, irreversível, sensível à segurança, custoso ou que altere permissões.
• Capturas de tela incluem uma versão de captura e equivalente textual; a imagem não é a única fonte de um valor ou instrução.
• Cabeçalhos e âncoras correspondem aos substantivos que os usuários pesquisam e permanecem estáveis para links profundos.
• Diferenças materiais de versão informam o intervalo afetado, substituição atual e consequência de migração.
• A data verificada reflete uma revisão comportamental, e uma equipe ou função nomeada é responsável pela próxima revisão.
• Procedimentos, diagnóstico e histórico de versões linkam para páginas canônicas irmãs em vez de serem duplicados de forma incompleta.
• A indexação pública é intencional; material obsoleto, duplicado, privado e sensível à segurança tem tratamento de busca apropriado.
• Registros de FAQ correspondem a respostas visíveis, e o CTA respeita a próxima tarefa do leitor em estágio de suporte.

Erros comuns

Escrever uma página de destino de recurso para um usuário existente. “Desbloqueie exportações poderosas” atrasa o fato de que o leitor precisa. Comece com comportamento, aplicabilidade e restrições; o texto de benefício pertence apenas onde esclarece o propósito.

Transformar toda tarefa em documentação. Uma configuração de 20 etapas enterrada sob uma lista de campos não atende nem à consulta nem à conclusão. Separe o procedimento ordenado em um guia prático e vincule-o a partir do pré-requisito ou seção de tarefa relacionada relevante.

Publicar uma página por rótulo de interface. Páginas finas se sobrepõem e multiplicam a manutenção. Agrupe campos em torno de um objeto de produto estável, a menos que uma configuração tenha comportamento distinto.

Usar “mais recente” como versão. Mais recente muda. Informe a versão testada, intervalo suportado, plataforma e data de verificação, depois atualize-os ao longo do processo de lançamento.

Manter páginas antigas e novas indexáveis sem limite. Consolide comportamento compatível; caso contrário, identifique a versão antiga, link para a página atual e controle a indexação intencionalmente.

Esconder pré-requisitos dentro de erros. Se apenas Administradores podem alterar um campo, diga isso antes da referência. Não faça um Visualizador descobrir o limite de função depois de seguir um exemplo.

Copiar capturas de tela em vez de comportamento. Uma captura é evidência de um estado de interface, não a especificação. Escreva rótulos, caminhos, valores e condições em texto acessível e registre a versão capturada.

Falsificar atualização. Alterar a data sem retestar o comportamento faz a página parecer mais segura enquanto aumenta o risco. Atualize o registro de verificação apenas depois que seu responsável verificar as afirmações aplicáveis.

Deixar a busca pública expor detalhes internos. Caminhos internos de escalonamento, segredos, identificadores de clientes, instruções de exploração e comportamento não anunciado não se tornam seguros porque reduzem o esforço de suporte. Separe o help público do conhecimento autenticado e interno.

Links internos

Link para cima para tipos de post SEO quando o autor pode precisar de um formato de resposta diferente. Link de um pré-requisito de documentação para o guia prático canônico apenas quando o leitor precisar concluir aquela tarefa primeiro. Link de um estado de erro para solução de problemas em vez de inserir uma lista genérica de correções. Link de uma diferença de versão para o evento de lançamento quando o histórico de alterações adicionar contexto; notas de versão devem link de volta para a documentação atual como a fonte duradoura da verdade.

Organize links em torno de objetos de produto e estado do leitor. Mantenha um link específico junto à afirmação que cria a próxima pergunta, em vez de depender de uma longa lista de artigos relacionados.

Uma página canônica atual deve ser a dona do comportamento estável. Mantenha páginas de versão apenas para comportamento materialmente diferente que os usuários ainda precisam, e torne essa distinção explícita. Use âncoras estáveis como #retention, não #tabela-2.

Como medir resultados

Meça se os usuários recuperam a resposta correta para sua versão. Apenas tráfego é evidência fraca: um pico pode refletir um produto quebrado ou uma resposta obsoleta.

Registre consultas-alvo, URL de ranqueamento, indexabilidade, versões suportadas, pesquisas de suporte, saídas para tarefas relacionadas e um evento de produto adequado. Depois revise:

• impressões de busca e visitas qualificadas para consultas de objeto de produto, campo, limite, sintaxe, função e versão;
• refinamentos de busca interna, buscas com resultado zero e buscas repetidas que revelam terminologia ausente;
• engajamento com seções ancoradas em vez de tempo indiferenciado na página;
• cliques para o destino correto de configuração, solução de problemas, versão ou suporte;
• contatos de suporte cuja pergunta a página deveria responder, segmentados por versão e função quando a privacidade permitir;
• citações que preservam o valor junto com seu plano, versão, unidade ou pré-requisito;
• URLs obsoletas ainda ranqueando ou sendo citadas após consolidação ou desativação;
• mudanças na documentação causadas por lançamentos, alterações de interface, mudanças de política e casos recorrentes de suporte.

Use monitoramento de prompts para perguntas de consulta com marca e variantes de versão. Use inteligência de fontes e citações para ver qual URL um mecanismo de resposta cita e se seu resumo preserva as condições. Abra o AmICited Cockpit para comparar URLs citadas, visibilidade, atividade de landing orgânica e o evento de produto ou suporte escolhido na mesma janela de observação.

Siga como medimos resultados para separar descoberta, representação, engajamento, progressão de tarefa e retenção. Anote versões e incidentes antes de interpretar movimentação. Uma resposta de clique zero funciona apenas quando preserva o valor atual e suas condições.

FAQ

Perguntas frequentes