Projetos pequenos não conseguem manter equipes separadas para tutorial, reference e suporte. Por isso, seus melhores sistemas de documentação são especialmente úteis como modelo.

A amostra inclui htmx, ripgrep, bat, jq e Starship: projetos populares, de escopo estreito e com source footprint compacto.

Método

Foram revisados guides oficiais, README, manual/reference, FAQ, troubleshooting, versionamento, localização e proximidade com o código. Oito critérios recebem 0–2 pontos; os dados do GitHub são de 15 de agosto de 2026.

Código compacto, audiência grande

Um produto focado pode servir uma audiência enorme; nesses casos a documentação vira a principal interface.

Starship
GitHub ★ 59,415
Código-fonte, MiB: 1.60
bat
GitHub ★ 60,182
Código-fonte, MiB: 0.57
ripgrep
GitHub ★ 67,297
Código-fonte, MiB: 1.91
htmx
GitHub ★ 48,965
Código-fonte, MiB: 2.06
jq
GitHub ★ 35,453
Código-fonte, MiB: 0.64
ProjetoEstrelas no GitHubCódigo-fonte, MiBFonte
Starship59,4151.60[S1]
bat60,1820.57[B1]
ripgrep67,2971.91[R1]
htmx48,9652.06[H1]
jq35,4530.64[J1]

Organização da documentação

Starship oferece o caminho mais completo; bat e ripgrep se destacam por README e profundidade; htmx pelo ensino conceitual; jq pela reference versionada.

Starship
16/16
bat
14/16
ripgrep
14/16
htmx
13/16
jq
12/16
CritérioStarshipbatripgrephtmxjq
Primeiro resultado rápido22221
Modelo mental21222
Exemplos22222
Reference completa22222
Troubleshooting22211
Versões e migração21122
Localização22100
Docs junto ao código22222

Cinco forças diferentes

Starship

Melhor equilíbrio

Guide, Configuration, advanced config, FAQ e traduções formam um sistema completo.

[S1] [S2]

bat

Melhor README

Uso, instalação, integrações, configuração e problemas reais ficam no mesmo material.

[B1] [B1]

ripgrep

Maior profundidade

README leva ao User Guide e FAQ; os guides cobrem filtros, encoding, binary data e configuração.

[R1] [R2]

htmx

Melhor explicação conceitual

Parte de HTML comum e chega a `hx-post`, triggers e targets.

[H1] [H1]

jq

Reference mais durável

Manuals por versão preservam um modelo filter/input/output estável.

[J1] [J1]

O que todos têm em comum

A estrutura segue as decisões do usuário, não a árvore do código.

PadrãoExemplo realO que adotar
README como entradaResultado rápido e rotas seguintes.Não transformar a home do repo em depósito.
Exemplo antes da abstraçãoAção real antes da teoria.Mostrar valor em cinco minutos.
Reference separadaGuide e reference têm funções diferentes.Separar aprendizado de exaustividade.
Problemas reaisFAQ expõe limitações desconfortáveis.Franqueza cria confiança.
VersõesManuals antigos e migration guides continuam disponíveis.Não apagar o passado.
Docs com códigoDocumentação segue o mesmo ciclo de mudança.Evitar um segundo ciclo de vida.

Stack documental para duas a cinco pessoas

README, Guide, Reference, FAQ/Troubleshooting, Migration e Contributing cobrem quase toda a jornada quando cada formato tem uma função clara.

  • README — Valor, instalação, exemplo, rotas
  • Guide — Tarefas principais
  • Reference — Opções e defaults
  • FAQ / Troubleshooting — Problemas reais
  • Migration / Changelog — Mudanças e atualização
  • Contributing — Mudanças em código e docs
CamadaFunção
READMEValor, instalação, exemplo, rotas
GuideTarefas principais
ReferenceOpções e defaults
FAQ / TroubleshootingProblemas reais
Migration / ChangelogMudanças e atualização
ContributingMudanças em código e docs

Fontes primárias

Somente sites oficiais, repositórios e dados da GitHub API.

[H1]htmx.org/docs/[H2]api.github.com/repos/bigskysoftware/htmx[H3]api.github.com/repos/bigskysoftware/htmx/languages[R1]github.com/BurntSushi/ripgrep/[R2]github.com/BurntSushi/ripgrep/blob/master/GUIDE.md[R3]github.com/BurntSushi/ripgrep/blob/master/FAQ.md[R4]api.github.com/repos/BurntSushi/ripgrep/languages[B1]github.com/sharkdp/bat[B2]api.github.com/repos/sharkdp/bat/languages[J1]jqlang.org/manual/[J2]api.github.com/repos/jqlang/jq[J3]api.github.com/repos/jqlang/jq/languages[S1]starship.rs/guide/[S2]starship.rs/config/[S3]api.github.com/repos/starship/starship[S4]api.github.com/repos/starship/starship/languages

Conclusão

Starship oferece o sistema mais completo.

bat mostra o poder de um README excelente.

ripgrep ganha por profundidade e franqueza.

htmx ensina melhor o conceito.

jq mantém reference estável ao longo dos anos.

Documentação grande nasce primeiro da disciplina: poucos formatos, bons exemplos, reference separada, troubleshooting honesto e docs publicadas com o código.