Notation

Notation é uma poderosa ferramenta de interface de linha de comando (CLI) projetada para desenvolvedores que desejam manter sua documentação junto com seu código. Ela preenche a lacuna entre escrever documentação em um formato simples e universal como o Markdown e publicá-la em uma plataforma versátil e colaborativa como o Notion. A filosofia central por trás do Notation é que a documentação deve viver com o código que descreve, estar sujeita aos mesmos processos de revisão e ser fácil de atualizar sem fazer login em serviços separados. Ele elimina a complexidade de gerenciar sites de documentação separados ou lutar com frameworks de front-end, oferecendo um fluxo de trabalho simplificado e centrado no desenvolvedor.

Ao usar o Notation, as equipes podem garantir que sua documentação esteja sempre atualizada com seu código-fonte. Quando o código é mesclado, a documentação correspondente pode ser publicada no Notion com um único comando. Isso torna a documentação acessível não apenas a outros engenheiros, mas também a membros da equipe não técnicos, como gerentes de produto, designers e equipe de suporte que estão confortáveis usando o Notion. A ferramenta aproveita todos os recursos nativos do Notion, incluindo sua poderosa pesquisa, capacidades de IA, formatação rica e opções flexíveis de compartilhamento, fornecendo um sistema de documentação robusto gratuitamente.

Como usar o Notation

Usar o Notation envolve um processo de configuração direto que integra seu ambiente de desenvolvimento local com seu espaço de trabalho do Notion:

1. Instalação: Instale o binário do Notation em sua máquina local usando um simples comando curl fornecido na documentação oficial. Isso torna o comando `notation` disponível em seu terminal.
2. Configuração: Crie um arquivo de configuração chamado `Notation.toml` no diretório `~/.notation/`. Este arquivo armazenará seu segredo da API do Notion e o nome da página pai no Notion onde você deseja publicar sua documentação.
3. Integração com o Notion: Você precisa criar uma nova integração interna em seu espaço de trabalho do Notion. Isso gerará uma chave de API secreta que você adicionará ao seu arquivo `Notation.toml`.
4. Conectar à Página: No Notion, navegue até a página que você designou como a página pai. Use o menu 'Conexões' para conceder à sua integração recém-criada acesso a esta página.
5. Escrever Documentação: Escreva sua documentação em arquivos Markdown dentro do repositório do seu projeto. Você pode organizar os arquivos em diretórios, que o Notation converterá em subpáginas aninhadas no Notion.
6. Publicar: Execute o comando `notation ship --src ` em seu terminal. O Notation analisará seus arquivos Markdown e estrutura de diretórios e, em seguida, criará ou atualizará automaticamente as páginas correspondentes em seu espaço de trabalho do Notion.

Recursos principais do Notation

• Conversão de Markdown para Notion: Converte automaticamente arquivos Markdown padrão em páginas do Notion lindamente formatadas. Suporta cabeçalhos, listas, blocos de código, tabelas, links e muito mais.
• Preservação da Estrutura de Diretórios: Replica sua estrutura de diretórios local como páginas aninhadas no Notion, facilitando a organização de documentação complexa.
• Fluxo de Trabalho Baseado em CLI: Integra-se perfeitamente ao ambiente de linha de comando do desenvolvedor e pode ser adicionado a pipelines de CI/CD para atualizações automatizadas de documentação.
• Metadados de Página Personalizados: Permite que você defina o título da página do Notion e o ícone de emoji diretamente do seu arquivo Markdown usando sinalizadores simples como `--title "Minha Página"` e `--emoji 🚀`.
• Conteúdo da Página Pai: Um arquivo especial `intro.md` pode ser usado para adicionar conteúdo diretamente à página pai principal, em vez de criar uma subpágina separada.
• Aproveita o Poder do Notion: Uma vez publicada, a documentação se beneficia da pesquisa avançada do Notion, recursos de IA integrados, edição colaborativa e opções flexíveis de compartilhamento (interno, público ou como um site).
• Manuseio de Links Relativos: Converte inteligentemente links relativos entre arquivos Markdown em links de página do Notion adequados, garantindo uma navegação perfeita em sua documentação.

Casos de uso para o Notation

O Notation é versátil e pode ser adaptado para várias necessidades de documentação:

• Wikis de Engenharia Internos: Crie e mantenha uma base de conhecimento centralizada para sua equipe de desenvolvimento, com a documentação vivendo ao lado do código relevante.
• Documentação de API Pública: Publique documentação de API clara e bem estruturada para desenvolvedores externos. A página do Notion pode ser tornada pública com um único clique.
• Guias e Manuais do Usuário: Desenvolva documentação voltada para o usuário que seja fácil para escritores não técnicos contribuírem (via Notion) e para desenvolvedores atualizarem (via Markdown).
• Documentação de Projeto: Mantenha todos os documentos relacionados ao projeto, de especificações técnicas a notas de reunião, organizados e em sincronia com o ciclo de vida de desenvolvimento do projeto.
• Base de Conhecimento Pessoal: Desenvolvedores podem usá-lo para gerenciar suas notas pessoais e referências técnicas, publicando-as em um espaço privado do Notion.

Vantagens do Notation

A principal vantagem do Notation é sua simplicidade e abordagem que prioriza o desenvolvedor.

• Documentação como Código: Ao manter os documentos no repositório, eles podem ser versionados, revisados e atualizados como parte do fluxo de trabalho de desenvolvimento padrão.
• Redução de Sobrecarga: Elimina a necessidade de gerenciar e implantar geradores de sites estáticos complexos como o Docusaurus ou aprender frameworks de front-end como o React.
• Fonte Única de Verdade: Garante que a documentação no Notion seja um reflexo direto dos arquivos Markdown no repositório, evitando a derivação de conteúdo.
• Acessibilidade Aprimorada: Torna a documentação técnica facilmente acessível e legível para não-engenheiros, promovendo uma melhor colaboração interfuncional.
• Custo-Benefício: A ferramenta em si é gratuita e de código aberto, e aproveita os níveis gratuitos ou existentes do Notion, tornando-a uma solução altamente econômica.

Preços e planos

Notation é uma ferramenta gratuita e de código aberto. Está disponível para download e uso sem custo. Os usuários estão sujeitos apenas aos custos associados ao seu plano do Notion (muitos casos de uso podem ser atendidos pelo plano gratuito do Notion) ou a quaisquer serviços de terceiros que possam usar para transformar sua página do Notion em um site com domínio personalizado, como o super.so.