Este mês faz um ano desde que assumi minha função atual e mais técnica da minha carreira. Eu não pretendia manter isso em segredo. Realmente, isso não influenciou muito na minha escrita.
A essa altura, estou insinuando que sim. A função me expôs a uma variedade de sistemas de computador criados por várias pessoas ao longo do tempo. Todos esses sistemas me obrigaram a assimilar rapidamente um imenso volume de conhecimento técnico.
Considerando minhas afinidades com engenharia de software e redação, uma coisa que se destacou em minha função foi a documentação. Eu provavelmente deveria ter previsto isso, mas não cheguei a isso enquanto acompanhava freneticamente tudo, ok? Eu vi documentação de tirar o fôlego guiando o leitor em uma jornada através do código e documentação que quase fez meus olhos vidrarem das paredes de texto pouco relevante.
Depois de ler dezenas de páginas, desenvolvi uma intuição sobre o que separava o exemplar do lamentável. O que se segue é uma destilação consciente dessa intuição.
A forma platônica (at) do bem
O que faz uma boa documentação? Fundamentalmente, trata-se de organização e facilidade de rastreamento visual. Aqui estão algumas manifestações disso, em nenhuma ordem particular.
Exemplos, lembretes, avisos, etc., estão incluídos em caixas de texto explicativo. Essa prática não apenas direciona a atenção do leitor para seu conteúdo, mas também ajuda a quebrar o que de outra forma seria uma parede uniforme de texto.
Uma pitada de formatação especial colorida também é ótima para dobrar a página como uma referência rápida. Por exemplo, se o leitor estiver familiarizado com a página, mas precisar procurar por uma ressalva importante, é mais fácil rolar até encontrar a caixa do que Ctrl-F procurá-la, o que pode falhar se não o fizer. lembre-se das palavras do conteúdo.
Trechos de código, inline ou em uma seção formatada separada, são denominados monoespaçados. Se o código estiver em sua página de documentação, provavelmente deve ser usado ou verificado em um projeto. Ambos são motivos suficientes para que seu código saia da textura.
Pontos de bônus quando o código embutido tem um fundo levemente sombreado. Novamente, isso é para ajudar a identificá-lo durante uma varredura visual. Grandes blocos de código devem ser incluídos em algo como uma caixa de texto explicativo. Se houver muito código que valha a pena ler, torne-o impossível de perder.
Os links são incluídos liberalmente. Os autores da documentação devem criar links para páginas em tantos sistemas relacionados quanto possível. Você já viu documentação com muitos links? Eu acho que não.
Os dados relacionais são organizados em tabelas. A melhor coisa sobre tabelas é que elas mostram associações. Eles se estendem horizontalmente, em que um item possui vários atributos, e verticalmente, em que muitos itens compartilham a mesma classe de atributo. Os computadores são construídos em associação. Isso é tudo o que uma variável atribuída, a base de praticamente todas as linguagens de programação, realmente é – um valor associado a um nome ou local de referência.
As tabelas também são outra ótima dica visual. Não posso falar sobre as preferências de todos, mas meu cérebro absorve melhor as informações se elas forem dispostas em uma tabela em comparação com um parágrafo. Imagine que você tenha que se lembrar o máximo que puder sobre uma página que leu apenas uma vez, duas semanas atrás, apenas com uma olhada rápida. O que o lembraria melhor: olhar para uma página com uma grande tabela ou apenas com texto?
O autor e as equipes envolvidas fornecem informações de contato. O software muda, mas os documentos nem sempre acompanham. Quando isso acontece, é útil saber com quem verificar se há atualizações. Qualquer coisa ajuda, até mesmo um nome, mas a informação de contato mais útil é um e-mail de lista de equipe. Companheiros de equipe individuais vêm e vão, mas o listserv geralmente envia pings para a equipe independentemente de quem está nela.
Diagramas estão incluídos. Tudo o que se aplica a tabelas se aplica a diagramas, mas ainda mais. As relações são ilustradas com formas simples, que nossos cérebros de predadores são bons em processar. Os diagramas são essenciais para entender os microsserviços porque há muita lógica acontecendo além de um aplicativo ou serviço específico em consideração.
Maus hábitos que você deve abandonar como, bem, maus hábitos
Além da ausência do acima, aqui estão algumas características que, por sua presença, tornam a experiência de consumo de documentação frustrante.
Organização é ruim. A má organização assume muitas formas, mas a mais flagrante é a ausência ou inconsistência dos títulos das seções. Mesmo que não haja um sumário vinculado internamente, ter títulos para percorrer torna muito mais fácil distinguir o que você procura de detalhes irrelevantes que o atrapalharão.
Não há indícios de veracidade das informações. Isso é sorrateiro porque é compreensivelmente tentador supor que, se estiver no documento, é verdade. Mas você realmente tem a evidência factual para afirmar isso? O software supera a capacidade dos desenvolvedores de escrevê-lo. Às vezes, os autores estão simplesmente errados.
Existem algumas maneiras de identificar documentos não confiáveis. Uma delas é a presença de palavras como “trabalho em andamento”, “proposto”, “proposto” etc., especialmente quando a página não é atualizada há algum tempo. Esses detalhes equivocados foram finalizados, os desenvolvedores esqueceram de atualizar a página ou o projeto foi descartado?
Outro sinal de precisão duvidosa é um documento que faz grandes afirmações sem links e que nenhuma outra página corrobora. Se você vir isso, pense duas vezes antes de confiar no que você lê.
A formatação é incompatível. Além de parecer ruim e tornar a página ilegível, a formatação malfeita mostra que o autor copiou e colou sem nenhum esforço de contextualizar ou adaptar a informação. Às vezes, a informação é tão precisa, mas outras vezes o contexto ausente pode levar o leitor confiante ao caminho errado.
Isso não é para lançar calúnias sobre os autores que tentam espremer na produção de documentação quando seu tempo já é escasso. Acabei de ver isso se tornar ruim o suficiente para aconselhar que observar a formatação instável é apenas cuidar de si mesmo.
Incluir um script e instruir os leitores a apenas executá-lo. Jamais, apenas execute um script. As intenções do autor geralmente são boas. Eles querem deixar o leitor descarregar algum fardo cognitivo. Mas o autor nunca pode ter certeza de que o caso de uso do leitor está alinhado com o que ele pretende com o script ou tem as habilidades para avaliar se é assim.
Por outro lado, o autor pode ter confiado em suposições irrealistas ou apenas escrito um roteiro descuidado. Você não precisa ignorar o script; você apenas tem que lê-lo antes de usá-lo para qualquer coisa.
Escreva os documentos que você deseja ler no mundo
Infelizmente, você não pode fazer outras pessoas escreverem documentos do jeito que você quer. Você pode tentar, mas vai parecer um idiota. A melhor abordagem é para você para escrever a documentação que adere às melhores práticas. Não é apenas mais útil quando você consulta suas anotações, mas também inspira outras pessoas a melhorar seu jogo.
Embora eu tenha seguido alguns dos hábitos construtivos mencionados desde o início, muitos deles eu peguei porque os localizei em outro lugar e pensei: “Vou começar a fazer isso”. Essa pessoa também pode ser você.
