Convenções de Escrita

Table of Contents

Esta postagem serve a alguns propósitos:

Definir escolas claras de formatação.
Servir como referência para mim. 🙃
Validar a formatação após fazer alterações ou atualizações.

Formatação de Texto

Negrito

Uso: Ações ou Ênfase Forte

Elementos da IU: Interações com componentes da interface, como botões, menus e caixas de diálogo (por exemplo, "Clique no botão Enviar").
Rótulos: Rótulos de informações identificadoras, geralmente seguidos por dois pontos ou hífen (por exemplo, Nome: ou Nome –).
Definições: Usado com moderação para introduzir um novo termo importante.
Ênfase: Chamar a atenção para algo importante sem recorrer a advertências (por exemplo, "Não feche a janela.").

Itálicos

Uso: Referências ou Ênfase Leve

Títulos e Publicações: Usado para títulos de livros, relatórios, artigos, periódicos, etc.
Ênfase:
- Uma informação relevante, mas não essencial para a ideia principal (ex.: "Os fusos horários são UTC, salvo indicação em contrário.").
- Usado com moderação para adicionar um toque de estilo (ex.: "Tínhamos acabado de concluir a migração quando…").

Riscar

Uso: Descontinuações ou Alterações

Indica uma mudança em relação a informações, declarações, ou modo de pensar anteriores.

Sublinhado

Uso: Evitar

Facilmente confundido com hiperlinks.

Advertências

As seguintes advertências serão usadas para fornecer informações adicionais.

NOTA	Usadas para fornecer contexto adicional ou esclarecimentos úteis que complementam o conteúdo principal.

DICA	Usada para compartilhar uma sugestão prática que pode tornar a tarefa mais fácil ou mais eficaz.

IMPORTANTE

Usada para destacar informações às quais o leitor deve prestar muita atenção para evitar confusão ou erros.

AVISO

Usada para aviso o leitor sobre ações que podem levar a problemas menores, como configurações incorretas ou resultados indesejados.

CUIDADO

Usada para alertar o leitor sobre ações que podem causar problemas graves, como perda de dados ou riscos de segurança.

Blocos da Barra Lateral

O título é opcional

As barras laterais são usadas para fornecer informações adicionais que complementam o contexto do texto principal.

Blocos Recolhíveis

Ocultarei as capturas de tela quando forem auxiliares.

Screenshot

Confira a documentação do Asciidoctor!

Normalmente, ocultarei a saída dos exemplos para não sobrecarregar o documento.

Example 1. Bloco recolhível dentro de um bloco de exemplo

ls -lha

Saída

total 36K
drwxr-xr-x 18 quinshanley staff  576 Mar 31 10:26 .
drwxr-xr-x 22 quinshanley staff  704 Mar 17 09:24 ..
-rw-r--r--  1 quinshanley staff 6.1K Mar 31 20:21 .DS_Store
drwxr-xr-x  6 quinshanley staff  192 Mar 31 10:26 .direnv
-rw-r--r--  1 quinshanley staff  283 Mar 31 10:26 .envrc
drwxr-xr-x 16 quinshanley staff  512 Mar 30 02:00 .git
drwxr-xr-x  3 quinshanley staff   96 Mar  2 11:51 .github
-rw-r--r--  1 quinshanley staff   10 Mar 28 19:33 .gitignore
-rw-r--r--  1 quinshanley staff    0 Mar 28 19:33 .gitmodules
-rw-r--r--  1 quinshanley staff   93 Mar 28 19:33 ACKNOWLEDGMENTS.adoc
-rw-r--r--  1 quinshanley staff  509 Mar 30 19:49 Makefile
drwxr-xr-x  7 quinshanley staff  224 Mar 31 11:28 bin
drwxr-xr-x  5 quinshanley staff  160 Mar 28 19:33 entrypoint.d
-rw-r--r--  1 quinshanley staff  308 Mar 28 19:33 entrypoint.sh
-rw-r--r--  1 quinshanley staff  569 Mar 28 19:33 flake.lock
-rw-r--r--  1 quinshanley staff  596 Mar 28 19:33 flake.nix
drwxr-xr-x 18 quinshanley staff  576 Mar 31 22:07 site
drwxr-xr-x  3 quinshanley staff   96 Mar 27 20:24 submodules

Lista de Descrição Horizontal

Usado para formatar uma lista de descritores e descrições de forma organizada.

Título é opcional

Descritor Normal	Este descritor não possui formatação.
Descritor em Negrito	Este descritor está em negrito.
Descritor em Negrito	Este descritor está em itálico.
`Cmd`+`Shift`+`N`	Este descritor é um atalho de teclado.

Mermaid Diagramas

graph LR;
A[Limão]-->B[Limonada];
B-->C[Lucro!]

sequenceDiagram
  Alice->>Bob: Olá
  Bob-->>Alice: Oi