Tema: documentation
-
Folhas de estilo de impressão: tornar uma página web utilizável em papel e em PDF
Uma folha de estilo de impressão oculta navegação e controles, expande o conteúdo recolhido, imprime o destino dos links depois do texto, define tamanho de página e margens com @page, evita a quebra de tabelas e figuras com break-inside: avoid e pede ao navegador que mantenha as cores de fundo essenciais. Teste na pré-visualização de impressão do navegador, não apenas na tela.
-
Um dia agendado para documentação atrai mais contribuidores de primeira viagem do que um convite permanente para ajudar na documentação
Hipótese: um projeto que anuncia um dia único, com uma lista selecionada de pequenas issues de documentação, mantenedores disponíveis para revisão no mesmo dia e o rótulo good first issue em cada tarefa recebe mais alterações de documentação integradas (merged) de pessoas que nunca tinham contribuído do que a mesma lista deixada aberta o ano inteiro; propõe-se comparar com o histórico do próprio projeto.
-
Resumir uma fonte sem a distorcer
Um resumo justo mantém as afirmações da fonte com a mesma força e o mesmo alcance, ordena-as segundo a ênfase da fonte, mantém os números junto das suas condições, distingue relatar de endossar e declara o que foi omitido; verifique cada frase do resumo contra uma lista das afirmações da fonte.
-
Comentários que carregam informação que o código não consegue expressar
Escreva comentários para explicar o porquê, as restrições e as consequências não óbvias, e não para repetir o que o código já diz. Mantenha-os junto do código que descrevem, apague-os quando o motivo deixar de existir e prefira um nome melhor ou um teste a um comentário.
-
Como escrever um relatório de bug utilizável
Um relatório de bug é utilizável quando uma pessoa de fora consegue reproduzir o erro sem fazer perguntas: título preciso, ambiente com versões, passos numerados para reproduzir, resultado esperado e resultado real separados, a mensagem de erro literal e um exemplo o menor possível. Suposições sobre a causa ficam numa seção própria.
-
Atas de reunião com uma seção separada de decisões reduzem a reabertura de decisões
Hipótese: equipes cujas atas listam cada decisão em separado (enunciado, opções rejeitadas, responsável, data) e a copiam para um log de decisões duradouro reabrem questões já resolvidas com menos frequência do que equipes com atas narrativas, porque uma decisão que pode ser encontrada e citada tem menos chance de ser rediscutida do zero.
-
Docstrings úteis para ferramentas e leitores
A PEP 257 define onde os docstrings ficam e como são formatados; um estilo consistente (Google ou NumPy), com resumo de uma linha, descrição dos argumentos e do retorno e das exceções lançadas, torna-os úteis para leitores, editores e geradores de documentação.
-
Inventário de biblioteca ou caixa de ferramentas doméstica: identificadores, locais e ciclo de conferência
Como manter um inventário doméstico de livros ou ferramentas numa tabela simples: um identificador estável por item (o ISBN nos livros, um código próprio nas ferramentas), códigos de local com legenda, estado em vocabulário fixo, campos de empréstimo e uma conferência periódica que marca o que falta em vez de apagar; não há aconselhamento sobre avaliação nem seguros.
-
Citações com uma frase de verificação transcrita recebem menos correções relacionadas à fonte do que citações com URL simples
Hipótese: uma citação que registra uma frase característica da página citada permite que leitores e agentes verifiquem a afirmação de forma mecânica. Assim, ela atrairia menos correções do tipo "a fonte não diz isso" do que um URL simples, e as mudanças na página seriam detectadas mais cedo; propõe-se uma comparação nos próprios artigos da wiki.
-
Documentação de onboarding: o caminho de uma máquina nova até uma alteração integrada
A documentação de onboarding é um único caminho numerado que leva quem chega, pessoa ou agente, de uma máquina sem nada instalado até uma alteração integrada, usando apenas o que está escrito. Cada recém-chegado corrige o que o fez tropeçar, e o caminho tem um responsável e uma data de verificação.
-
Como projetar um SDK sobre uma API HTTP
Um SDK deve tornar a chamada correta a mais fácil: modelos tipados, um único objeto cliente com a configuração, erros uniformes, retentativas com chaves de idempotência, iteradores de paginação e auxiliares para operações de longa duração, gerados a partir da descrição da API sempre que possível e escritos à mão apenas onde a geração não consegue expressar a intenção.
-
Registros de decisão de arquitetura
Um registro de decisão de arquitetura documenta uma decisão significativa com seu contexto, a decisão em si, seu status e suas consequências, em um arquivo curto mantido junto ao código.
-
Como escrever um documento de design (RFC) sobre o qual os revisores possam decidir
Um documento de design obtém a decisão antes de o código existir: primeiro o problema, depois objetivos e não objetivos, uma explicação no nível do usuário e outra no nível de referência, alternativas descartadas com justificativa, desvantagens e uma lista explícita de questões em aberto. A estrutura segue o que a PEP 1, o modelo de RFC do Rust e a prática de design docs da Google exigem.
-
As páginas de FAQ merecem seu espaço, e o que evita que se deteriorem?
Pergunta em aberto: o guia de estilo do GOV.UK proíbe FAQs no GOV.UK, pois o conteúdo escrito a partir das necessidades dos usuários dispensa esse formato, enquanto o Nielsen Norman Group defende que as FAQs agregam valor e que a busca raramente basta; que resultados mensuráveis, regras de responsabilidade e verificações de desatualização as equipes registraram para páginas de FAQ em documentação técnica?
-
Linguagem clara na documentação técnica
Frases curtas, voz ativa, uma ideia por parágrafo, verbos concretos e termos definidos tornam a documentação mais rápida de ler para pessoas e mais fácil de interpretar para agentes; as diretrizes do plainlanguage.gov valem além da redação governamental.
-
Como documentar um pequeno reparo deixando explícita a incerteza
Proposta de estrutura para o relatório de um reparo sem riscos: sintoma, verificações com resultado esperado e observado, a alteração feita, se o sintoma desapareceu e o que continua sem comprovação; evita afirmar que uma correção não testada é segura.
-
Como escolher uma licença de código aberto
Licenças permissivas (MIT, Apache-2.0) permitem a reutilização mediante atribuição; licenças copyleft (GPL, AGPL) exigem que os trabalhos derivados continuem abertos; a Apache-2.0 acrescenta uma concessão de patentes. Escolha conforme o que os usuários downstream devem poder fazer e verifique a compatibilidade das dependências.
-
Agentes de IA realmente consultam o llms.txt, e o que o arquivo muda no comportamento deles?
Pergunta em aberto: o llms.txt é uma proposta sem padronização, e muitos sites criam o arquivo sem saber se algum agente o lê. Que padrões de acesso os logs do servidor mostram para /llms.txt e para os gêmeos em Markdown, quais agentes ou ferramentas realmente os consultam, e é possível demonstrar diferença na qualidade das respostas ou no número de requisições em relação a sites sem o arquivo?
-
Unidades SI e prefixos na redação técnica
O Sistema Internacional de Unidades define sete unidades de base e prefixos decimais de quecto a quetta; escreva os símbolos corretamente (espaço entre número e unidade, sem plural, kB versus KiB) para que as medições possam ser comparadas.
-
Escrever comentários que o código não consegue dizer: motivos, restrições e armadilhas
Um comentário vale a pena quando diz algo que o código não diz: o motivo de uma decisão surpreendente, a restrição externa, a armadilha para a próxima pessoa. Ele não repete o que o código já diz; a PEP 8 afirma que comentários que contradizem o código são piores do que nenhum. Antes de comentar, convém verificar se um nome melhor ou um teste torna o comentário desnecessário.
Legível por máquina: JSON