Exemplos são a melhor documentação

• Quando desenvolvedores buscam documentação, em 95% dos casos um exemplo simples já é suficiente, mas só em cerca de 5% dos casos é possível encontrar exemplos na fonte oficial
• A documentação técnica oficial normalmente é escrita tendo como público pessoas profundamente imersas naquele ecossistema, o que exige de desenvolvedores que transitam entre vários projetos e linguagens uma quantidade considerável de energia mental para reconstruir o contexto
• Ao olhar a documentação da função max() do Python, há muito conhecimento prévio necessário para entender a sintaxe da definição da função e os conceitos envolvidos, mas com 5 linhas de exemplo já é possível entender imediatamente
• O clojuredocs.org da comunidade Clojure oferece documentação prática por meio de exemplos enviados por usuários e é um caso exemplar que aumenta a utilidade real ao incluir até funções relacionadas
• Mesmo grandes projetos de software raramente oferecem os 4 tipos de documentação, e por isso os desenvolvedores acabam procurando tutoriais não porque precisem de orientação, mas porque precisam de exemplos

---

A importância dos exemplos ao buscar documentação

• Quando desenvolvedores procuram documentação, em 95% dos casos um único exemplo já basta
• No entanto, só em cerca de 5% dos casos é possível encontrar exemplos na fonte oficial
• A maior parte da documentação técnica oficial é escrita tendo como público padrão pessoas profundamente imersas no ecossistema
• Muitos desenvolvedores precisam, no dia a dia, fazer malabarismo mental com vários "mundos" ao mesmo tempo
  • Trocas frequentes entre projetos, linguagens e frameworks
  • Grande consumo de energia mental para restaurar o contexto e entender a situação

Análise do caso da documentação do Python

• Exemplo da função max() na documentação do Python 3
  • max(iterable, /, *, key=None): retorna o maior item
  • Em seguida, a explicação continua em 5 parágrafos curtos
• Conhecimento de Python necessário para entender essa documentação
  • O significado de * em uma definição de função
  • O significado de / em uma definição de função
  • O conceito de "positional-only parameter separator"
  • O conceito de iterable
  • O conceito de keyword-only arguments
  • O significado geral do parâmetro key
• É preciso ler o texto para entender que valores passar e como chamar a função na prática

O efeito de exemplos simples

• Reconhece-se que detalhes importantes não podem ser omitidos apenas em nome da concisão
• Ainda assim, muitos desenvolvedores chegam a essa página simplesmente para descobrir rapidamente como passar uma função de ordenação personalizada (key) para a função max
• Se houvesse um exemplo como o abaixo, seria possível obter imediatamente a informação desejada

  max(4, 6) # → 6  
  max([1, 2, 3]) # → 3  
  max(['x', 'y', 'abc'], key=len) # → 'abc'  
  max([]) # ValueError: max() arg is an empty sequence  
  max([], default=5) # → 5  
  

• Com exemplos, é possível entender de forma fácil e intuitiva

Um caso exemplar da comunidade Clojure

• O clojuredocs.org é um projeto comunitário do ecossistema Clojure
  • Usuários contribuem com exemplos sobre funções embutidas
  • É um recurso indispensável na programação do dia a dia
• Páginas de exemplo: into, spit, map
• Características dos exemplos
  • Incluem não apenas a função em si, mas também funções relacionadas
  • Aumentam a utilidade prática e a aplicabilidade real

Limites da documentação atual

• Mesmo grandes projetos de software raramente oferecem os 4 tipos de documentação
  • Referência: Sistema de documentação da Divio
• Motivo pelo qual se hesita em clicar no link "Documentation"
  • Na maioria das vezes, trata-se de uma referência de API auto-gerada, concisa e difícil de ler
• O verdadeiro motivo pelo qual desenvolvedores procuram tutoriais
  • Não é porque precisam de orientação, e sim porque precisam de exemplos
  • Tutoriais são mais úteis porque incluem exemplos

[sonnet]

Sinceramente, acho que isso se aplica principalmente a Java e Python. Também são ecossistemas em que o chauvinismo da própria linguagem e uma cultura fortemente isolada em termos de paradigma são marcantes.
Tomando Python como referência, o que foi dito faz sentido, mas quando você estuda várias linguagens, esses 5% parecem um baita exagero.

[kuber]

Venha para Go, onde o código é a própria documentação~
Aqui a gente desenvolve fuçando o código de teste, mesmo sem README

[pjtco]

Achei que só eu era burro demais pra não conseguir entender a documentação oficial kkk
Sério, se só jogarem um exemplo e derem uma explicaçãozinha, dá pra entender rapidinho.....

[nemorize]

Acho que o PHP seria ao mesmo tempo um ótimo exemplo e o pior exemplo possível.

É um bom exemplo porque a documentação oficial permite enviar conteúdo contribuído por usuários, então dá para conferir vários exemplos de código.

...mas também é o pior exemplo porque o PHP tem muitas pequenas questões de BC nas funções embutidas, e as contribuições de exemplo são praticamente todas de versões da época do onça, então acabam se misturando coisas sutilmente diferentes do funcionamento real, o que só aumenta a confusão... kkk..k...

[savvykang]

Nos antigos documentos de desenvolvimento de iOS ou Cocoa, havia uma seção separada de casos de uso; talvez esse seja o jeito certo de documentar, não? Exemplos, assinaturas de funções e explicações do comportamento, tudo isso é necessário.

[aer0700]

Se antes a falta de conteúdo na documentação oficial era compensada pelo Stack Overflow e por pesquisas no Google, hoje em dia parece que os LLMs estão preenchendo essa lacuna.

[GN⁺]

Comentários no Hacker News

• O melhor da documentação do Python antigo era abrir a documentação de uma biblioteca e encontrar uma seção em que os argumentos da função e os valores de retorno estavam claramente organizados. Hoje em dia, é uma pena que muita documentação de bibliotecas JavaScript ou Python forneça apenas exemplos. Exemplos são ótimos para montar algo rapidamente, mas, para corrigir problemas ou aprender uma biblioteca, explicações dos argumentos são essenciais. É bom quando exemplos vêm como bônus, mas eles não podem ser tudo

  • Na verdade, o que você quer são definições de tipos. Definições de tipos servem como boa documentação. As ferramentas do sistema de tipos já mostram muita informação diretamente no editor ou na IDE, então a necessidade de ir procurar e ler a documentação diminui. O aumento da documentação centrada em exemplos hoje em dia vem dessa mudança de fluxo de trabalho. A ideia é que não faz sentido repetir na documentação o que as ferramentas de tipos já fornecem. Quando olho a documentação, me interesso mais por "que problema esta ferramenta pode resolver" do que pelos detalhes dos argumentos. Exemplos são excelentes para mostrar essa possibilidade. Quando quero resolver um problema específico, ver exemplos me permite julgar rapidamente se a ferramenta vai ajudar. --- Se houver um sistema de tipos, eu prefiro ver exemplos primeiro. Se não houver sistema de tipos: 1) fico insatisfeito. 2) quero ver exemplos primeiro e depois os detalhes sobre argumentos/retorno/estruturas de dados

  • Boa documentação precisa dos dois. Primeiro você explica os detalhes e depois adiciona vários exemplos para permitir conferir o conteúdo. Às vezes, só exemplos podem bastar, mas, quando há combinações demais de opções, é quase impossível mostrar tudo com exemplos. Por isso, é preciso explicar primeiro cada opção e depois preparar exemplos dos casos mais variados possível para que o leitor consiga adaptar. E documentação boa é muito difícil de fazer, e hoje em dia é realmente rara

  • Não concordo totalmente. Documentação no estilo Javadoc é documentação de programação baseada em tipos e docstrings inline. Ela é necessária, mas, em vez de ir para a web, é mais eficiente olhar o próprio código. Guias como exemplos ou QuickStart são indispensáveis. Eles reduzem a barreira de entrada da biblioteca. Só olhando o código, não dá para entender facilmente como usar a API. No passado, houve muitas bibliotecas Java que só ofereciam Javadoc, e já tive a experiência incômoda de não saber como usá-las

  • Acho que exemplos bem comentados são o melhor. Mas eles não podem substituir a documentação tradicional

  • Fico me perguntando se você já considerou que outras pessoas podem ter estilos de aprendizado diferentes do seu. Não entendo por que existe tanta resistência à ideia de que exemplos devam fazer parte da documentação. Exemplos reduzem o atrito da troca de contexto em várias situações

• As páginas man do Unix também precisam desesperadamente de exemplos. Em geral, elas são usadas apenas como referência para quem já conhece bem a ferramenta, então não ajudam em nada iniciantes. Boa documentação precisa das duas coisas

  • Concordo completamente. Gostaria de lembrar a todos os autores de páginas man que existe uma seção convencional chamada EXAMPLE. Vale consultar a documentação oficial do man(1)

  • Eu nunca senti esse problema. Primeiro vou escrevendo código e aprendendo os comandos ou termos, e depois vou olhando um por um os códigos de erro retornados, suas causas e o significado dos parâmetros. Mesmo sem exemplos, se a documentação for completa, isso basta. Em compensação, fornecer só exemplos sem nenhuma explicação é realmente o pior caso. Como pode existir documentação em que você nem sabe o que são os parâmetros ou o que significam?

  • Gostei de saber que o Stack Overflow já tentou algo parecido no passado. Funcionou em beta de 2016 a 2017 com o nome Stack Overflow Documentation. A proposta era criar documentação centrada em exemplos, mas foi encerrada. Ainda assim, o conteúdo deixado pela comunidade continua disponível sob CC BY-SA

  • Dê uma olhada no cheat.sh. Eu uso direto em scripts com curl cheat.sh/"$1"

  • Sempre me surpreende quantas páginas man têm exemplos. Ainda assim, há bastante espaço para melhorar isso de forma mais abrangente

• Exemplos não são úteis só para iniciantes ou usuários ocasionais. Usuários experientes também precisam de documentação formal, ou seja, documentação com todas as configurações de parâmetros. Por exemplo, a documentação do requests sempre faz o Google me mandar para páginas cheias de exemplos como o Quickstart, o que é frustrante. Todo mundo sabe fazer um HTTP GET, mas é difícil encontrar quais são as outras opções, como funciona o timeout ou se raise_for_status ignora um 204. Os dois são necessários, mas, se o tempo de desenvolvimento for curto, eu escolheria primeiro fornecer a documentação correta. Link para exemplos do requests Quickstart

  • Ao ver exemplos, é muito mais fácil entender o comportamento do que com documentação em estilo de referência. As pessoas são ruins em tudo isso: nomear, organizar conceitos e escrever documentação. Recentemente também perdi horas por causa de um parâmetro que só funciona sob certas condições. O código era complexo demais para entender de imediato, e até um LLM me informou erroneamente que era um parâmetro sem documentação. No fim, o mais eficiente foi montar código de exemplo até encontrar o comportamento desejado. Exemplos condensam vários pontos importantes e permitem verificar rápido. Já a documentação de API tenta cobrir tudo e, por isso, é difícil de manter e nem sempre comunica o essencial. E, a menos que esteja claro, eu nunca confio no comportamento de uma biblioteca. Se não estiver explicitamente mostrado no README ou definido por tipos, considero que pode mudar a qualquer momento. No fim, escrevo o código de chamada da forma mais defensiva possível

  • Exemplos são importantes não só para iniciantes, mas para todo mundo. Com um exemplo de 5 segundos, você ganha a eficiência de uma hora de leitura de documentação e experimentação. Alguns documentos do git são assim, e o mesmo vale para funções que são simples em essência, mas difíceis de explicar. Mesmo que o desenvolvedor só possa criar uma coisa, ele certamente tem fôlego suficiente para entregar exemplos e documentação. Os dois devem ser oferecidos, com exceção apenas dos casos realmente óbvios

  • Concordo. Boa documentação quase precisa especificar claramente todo o comportamento do programa, e é difícil cumprir esse papel só com exemplos

  • Dá para ter os dois ao mesmo tempo. Exemplos e documentação técnica não são incompatíveis

  • A fala sobre usuários ocasionais é exatamente o que eu queria dizer. Cada vez que se muda de projeto, linguagem ou framework, há um custo mental considerável para recuperar o contexto e entender a situação

• Muita gente fala mal de Perl, mas a documentação de Perl realmente ajuda. Sempre há uma seção SYNOPSIS no começo, com código de exemplo que já dá para usar na hora. Depois vêm a explicação, a referência e exemplos adicionais. Exemplos: documentação do bigrat, documentação do Archive::Tar. Ao escrever documentação de projeto, vale a pena se inspirar no estilo do Perl. E o próprio estilo está bem descrito

  • Usei Perl no começo dos anos 2000 e acabei voltando a usá-lo por acaso em 2014, e foi como se tudo voltasse à memória. Talvez por causa da visão linguística e da atitude do Larry Wall, mas aquilo deixa uma impressão forte. Não é pela precisão matemática, e sim por dar muito a sensação de "conversar com um amigo"

• Os dois são necessários. Exemplos dão uma noção imediata, facilitam a integração, e as explicações detalhadas de parâmetros e configurações ajudam a resolver problemas complexos da ferramenta e a entendê-la por completo. Quando falta um dos dois, fica realmente ruim. Só bibliotecas muito simples talvez consigam explicar tudo apenas com exemplos

  • Tanto exemplos quanto documentação de referência são necessários. Se possível, também é bom acrescentar um ambiente REPL. Se você puder modificar e testar os exemplos na hora, muitas deficiências da documentação acabam sendo compensadas

• O framework Diátaxis mostra muito bem que existem vários tipos de documentação, cada um com sua função. Não se trata de qual é "a melhor", mas de usar cada uma conforme necessidades diferentes. Site oficial do Diátaxis

  • Isso deveria estar no topo. Fiquei até frustrado que a menção ao Diátaxis só aparecesse depois de tanta discussão. Minha visão é que exemplos são centrais na documentação, mas se parecem mais com uma "técnica de documentação" importante do que com um "tipo de documentação" independente

  • Exato! Exemplos (ou tutoriais) são um dos pilares do ensino de sistemas. Não sei ao certo quem criou isso primeiro, mas o link parece semelhante ao do autor citado no fim do artigo: > "É raro até para projetos grandes ter os quatro tipos de documentação. Por isso, às vezes dá até hesitação de clicar no link ‘Documentation’" Eu gosto de documentação mais explicativa. Quando se entende a estrutura ou o motivo do funcionamento, fica fácil absorver exemplos e tutoriais. Quando redatores técnicos experientes ou educadores estabelecem bem esse quadro desde o início, o efeito é grande. Já a referência de API costuma ser mais necessária ao criar wrappers ou implementações compatíveis. Muitos projetos, originalmente, começaram com referências de API privadas, e documentar era basicamente tornar isso público. Veja o sistema de documentação da divio

  • O conceito do Diátaxis é excelente. Só que não é fácil aplicá-lo a projetos reais. A proporção de tipos de documentação necessária varia de projeto para projeto, e oferecer todos os formatos em um único site é ineficiente. Essa proporção também muda continuamente conforme a comunidade cresce e se especializa. Eu queria que houvesse um método mais prático. Documentação é um desafio difícil, e espero que um dia apareça uma solução melhor. Por enquanto, a qualidade acaba dependendo do tempo e da especialização investidos, e a realidade é que normalmente faltam ambos

• Sinto muito esse problema em Unity e Unreal. Especialmente na documentação de nós do Unreal, muitas vezes eles só repetem uma captura de tela do nó e o nome dele, sem explicar em nada como aquilo realmente se usa. No Unity também procuro a documentação querendo entender o uso correto de alguma função, mas às vezes simplesmente não há conteúdo nenhum. Se pudesse, eu mesmo contribuiria com exemplos para a documentação do Unity

  • A documentação horrível do Unreal também me faz perder uma quantidade enorme de tempo. Lá existe muito essa ideia de que "o código é a documentação", mas aquela "explicação com captura de tela de nó" para Blueprint é realmente risível

  • Sobre £JOB, quando as pessoas usam $job, fico me perguntando se estão usando no sentido de trabalho remunerado (task) ou se é só um nome de variável. A essa altura, minha visão de mundo já está abalada

• Eu uso ImageMagick com frequência e sempre acabava pesquisando exemplos no Google. Então reuni minhas anotações pessoais em uma pequena coletânea de exemplos de comandos. Também acrescentei explicações detalhadas para cada argumento. Acho que, como neste post do blog, não basta ter só exemplos; é preciso ter explicações também. Ainda está em rascunho, mas, para tarefas do dia a dia como redimensionamento, otimização e criação de camadas, já é bem útil. Link para minhas notas públicas

• Exemplos de código podem ser executados como testes de unidade para evitar que a documentação fique desatualizada ou quebre. Essa é uma vantagem que linguagem natural não tem

  • Agora, com o avanço dos LLMs, também deve ser possível tentar verificar, por exemplo, a precisão da documentação de APIs

• Opinião radical: se a especificação de um método específico não puder ser intuída naturalmente só pela assinatura e por alguns exemplos representativos, então esse método está tentando fazer coisa demais. Também não tenho vontade de aprender abstrações engessadas nem exceções complexas

  • Acho que não. Exemplos são necessários para mostrar não só aquele método, mas também "como usá-lo junto com outros métodos". Mesmo que fosse possível deduzir tudo só pela assinatura do método, ainda é fácil deixar passar partes importantes, como configurações omitidas, preparação prévia ou tratamento do resultado. Por isso, exemplos são indispensáveis

[howudoin]

No ecossistema Java e na cultura de orientação a objetos, havia especialmente muitas frases explicativas sem sentido e documentação formalista; e, nos frameworks da linha do Python que herdaram esse clima, os exemplos também são especialmente fracos.

Exemplo de documentação sem sentido
add(left, right) - soma o operando da esquerda e o operando da direita

O que realmente importa, como o tipo de dados dos parâmetros, as exceções que podem ser retornadas, o formato do valor de retorno ou a estrutura de funcionamento, isso não é explicado.

Se fosse algo como a man page da linguagem C, só com uma explicação curta já daria para usar, nem que fosse inferindo pela função e pelos nomes dos parâmetros.