Guia de estilo e conteúdo

Este guia fornece uma visão geral do conteúdo que deve ser incluído na documentação do Zammad, além de diretrizes de formatação e estilo para garantir clareza e legibilidade.

As primeiras seções tratam de informações e regras gerais. Uma seção com exemplos segue no final.

Se você tiver dúvidas, sinta-se à vontade para perguntar em nossa comunidade. Se quiser contribuir, também pode conferir nossa página de contribuição ou perguntar em uma issue para começar.

Suposições sobre o público

A documentação presume que os usuários têm um entendimento básico de como usar navegadores web e estão familiarizados com conceitos comuns de design de software. Isso significa, por exemplo, que os recursos são descritos em detalhes, mas não a ponto de explicar como abrir um menu suspenso.

O administrador do Zammad também deve ter um entendimento técnico básico e estar familiarizado com os fluxos de trabalho e processos de comunicação da sua empresa.

Para instâncias auto-hospedadas, os administradores de sistema também devem estar familiarizados com noções básicas de administração de sistemas Linux. O acesso ao sistema hospedeiro (por exemplo, via SSH) e as permissões administrativas são considerados garantidos.

Conteúdo

A documentação tem como objetivo incluir informações sobre:

• Como usar o Zammad
• Como gerenciar o Zammad como administrador (por exemplo, configurá-lo após a instalação, ajustar configurações, configurar recursos)
• Diferentes formas de instalar o Zammad
• Guias adicionais caso seja necessária configuração do sistema (hospedeiro) e/ou configuração de sistemas de terceiros.

Quanto ao nível de detalhe, as suposições sobre o público devem ser consideradas. Como um dos objetivos do Zammad é ser intuitivo e amigável, não há necessidade de descrever cada clique em detalhes. No entanto, etapas importantes devem ser incluídas. Os leitores devem alcançar seus objetivos da forma mais rápida e fácil possível, sem precisar ler muito.

Devido ao fato de que uma documentação não pode cobrir tudo (caso contrário, estaria em um nível de detalhe quase de código), a relevância também deve ser considerada. Se partes com um caso de uso comum estiverem faltando, deve-se pretender incluí-las.

Estilo e regras

As próximas seções cobrem coisas gerais a considerar ao escrever a documentação. Depois delas, você encontra uma seção com alguns exemplos sobre como formatar e estruturar o conteúdo.

Fundamentos

• A documentação é escrita na linguagem de marcação Markdown. Os arquivos-fonte têm a extensão .md.
• O sistema usa o Vitepress para construir o site.
• O idioma dos arquivos-fonte é inglês americano.
• A tradução da documentação é feita via Weblate, consulte a seção de tradução na página de contribuição para mais detalhes.

Estilo

• Use frases curtas e claras e priorize a informação em vez da complexidade.
• Título da página e cabeçalhos: coloque em maiúscula a primeira letra de todas as palavras, exceto palavras menores (veja title case).
• Use separação em trilha de navegação para caminhos e locais com > como separador e formate o caminho em itálico, por exemplo, Settings > Channels > Chat.
• Use destaque de código para enfatizar trechos de programação.
• Use caixas de informação, dica, aviso e perigo quando necessário.
• Use uma caixa de detalhes quando o conteúdo pode não ser relevante para todos os leitores ou pode quebrar o fluxo de leitura de outra forma.
• Se disponível, use ícones para botões importantes da interface, como ＋ e ✕ (veja exemplos abaixo).
• Use marcação de tecla como ctrl e x para destacar o pressionar de uma tecla (veja exemplos abaixo).
• Inclua capturas de tela quando necessário. A forma preferida de adicionar capturas de tela do Zammad é criá-las automaticamente usando o Cypress. Isso apoia a manutenibilidade da documentação, pois as capturas de tela são regeneradas a cada execução do pipeline de build. Observe que o uso do Cypress não faz parte desta documentação.
• Forneça instruções passo a passo com explicações claras.
• Use exemplos ou cenários para ilustrar conceitos.
• Inclua imagens ou diagramas relevantes quando necessário.
• Escreva abreviações por extenso na primeira vez que forem usadas, ou inclua-as no glossário e link para elas. Abreviações amplamente usadas e comuns podem ser excluídas desta regra.
• Em caso de dúvida, alinhe-se à documentação existente.

Convenções

A stack da documentação inclui verificações automatizadas (linting) para garantir conformidade com o guia de estilo e regras comuns para arquivos Markdown. Para verificar se suas alterações estão em conformidade, execute pnpm lint para realizar a verificação. Alguns dos problemas identificados podem até ser corrigidos automaticamente executando pnpm lint:fix. Certifique-se de executar a verificação antes de fazer commit das suas alterações. Caso contrário, o build da documentação falhará.

O linting usado tem algumas regras integradas que você pode encontrar no repositório oficial. Algumas regras importantes e personalizadas são mencionadas abaixo.

• O comprimento de linha de 120 caracteres no arquivo-fonte não pode ser excedido para texto padrão. Certifique-se de usar uma quebra de linha antes de atingir esse limite. Um indicador visual no seu editor pode ser útil. Isso não se aplica a conteúdo especial, como caminhos para capturas de tela e links longos.
• Múltiplas linhas vazias consecutivas não são permitidas.
• Linhas vazias antes e depois de cabeçalhos e blocos de código cercados são obrigatórias.
• Use ``` (crases) para blocos de código cercados, seguidos de uma tag de linguagem obrigatória, por exemplo, ruby ou sh. Se nenhuma linguagem for aplicável, use plain.
• Use - para listas com marcadores (listas não ordenadas) como esta.
• Para distinguir facilmente entre negrito e itálico, use _ ao redor do texto para itálico e ** para negrito (por exemplo, _itálico_ vs. **negrito**).
• Múltiplos cabeçalhos com o mesmo conteúdo não são permitidos.
• Cada documento deve ter exatamente um cabeçalho h1 como título.
• A resolução das capturas de tela de página inteira manuais para visualização mobile é 400x867 pixels.
• A resolução das capturas de tela de página inteira manuais para visualização desktop é 1920x1080 pixels.

Exemplos

Texto e interface

Type	Highlighting in documentation	Markdown syntax
Labeled buttons	Sign in	`Sign in`
Fields and UI elements	Name	**Name**
Locations/paths	Settings > Channels > Email	_Settings > Channels > Email_
Keyboard shortcuts	x	[[x]]
Add button	＋	::+::
Delete button	✕	::x::
Action menu	︙	::a::
Copy to clipboard button		::c::

Estrutura de cabeçalhos

Todo arquivo de documentação deve incluir exatamente um título de nível superior (como # Title). Níveis abaixo devem sempre conter pelo menos duas seções. Se existir apenas uma seção, considere mesclá-la com o conteúdo de nível superior.

Exemplo:

# Título da página

## Seção 1

### Seção 1.1

### Seção 1.2

## Seção 2

Seção com selo custom text

Este título de seção usa um selo do tipo "warning". Há outros selos disponíveis, veja https://vitepress.dev/reference/default-theme-badge#usage.

Uso:

Details

Texto/título para adicionar um selo <Badge type="warning" text="custom text" />

Caixas personalizadas

INFO

Esta é uma caixa de informação.

Uso:

Details

::: info
Esta é uma caixa de informação.
:::

TIP

Esta é uma dica.

Uso:

Details

::: tip
Esta é uma caixa de dica.
:::

WARNING

Este é um aviso.

Uso:

Details

::: warning
Esta é uma caixa de aviso.
:::

DANGER

Este é um aviso perigoso.

Uso:

Details

::: warning
Esta é uma caixa de aviso perigoso.
:::

Details

Este é um bloco de detalhes.

Uso:

::: details
Este é o conteúdo mostrado no estado expandido.
:::

Listas de definição

Primeiro termo tag1

Esta é a definição do primeiro termo.

Segundo termo tag1 tag1

Esta é uma definição do segundo termo.

Esta é outra definição do segundo termo.

Uso:

Details

Primeiro termo <Badge type="info" text="tag1" />
: Esta é a definição do primeiro termo
  com outra linha.

Destacando com caixas

Para destacar diferentes opções ou variantes, caixas clicáveis podem ser usadas.

🛠️

Simples e minimalista, sempre

Lorem ipsum...

This is a link

Outro recurso legal

Lorem ipsum...

Outro recurso legal

Lorem ipsum...

A definição do conteúdo é feita via frontmatter, veja o exemplo a seguir (reflete as caixas acima):

features:
  - icon: 🛠️
    title: Simple and minimal, always
    details: Lorem ipsum...
    link: https://zammad.com
    linkText: This is a link
    target: _blank
  - icon:
      src: /assets/logo.svg
    title: Another cool feature
    details: Lorem ipsum...
    link: https://zammad.com
  - icon:
      dark: /assets/logo-flat-dark.svg
      light: /assets/logo-flat-light.svg
    title: Another cool feature
    details: Lorem ipsum...
    link: https://zammad.com

Para colocá-lo na área de conteúdo, simplesmente insira a referência <VPDocFeatures /> no ponto onde ela deve ser renderizada.

Imagens específicas de tema

Para direcionar recursos de imagem específicos a um único tema, você pode atribuir a classe CSS .dark-only ou .light-only à imagem correspondente:

![Imagem apenas para tema escuro](/assets/logo-flat-dark.svg){.dark-only}
![Imagem apenas para tema claro](/assets/logo-flat-light.svg){.light-only}

{.dark-only width=240}