Um exemplo concreto do que dá errado com a documentação da Apple
A documentação oficial da Apple para APIs de macOS e iOS é amplamente criticada por ser superficial, incompleta e difícil de navegar, especialmente em frameworks mais novos como SwiftUI. Desenvolvedores descrevem perder horas com tarefas básicas e recorrerem a LLMs, blogs de terceiros e documentos antigos arquivados da “velha Apple”, que eram muito mais completos; alguns argumentam que isso é consequência do ciclo anual de lançamentos da Apple, do sigilo interno e da baixa prioridade dada à redação técnica. Outros contrapõem que as APIs são utilizáveis se você entender padrões orientados a objetos e ler com atenção, mas há uma preocupação generalizada de que a documentação ruim prejudica a produtividade e está empurrando desenvolvedores para ferramentas assistidas por IA e para plataformas alternativas com documentação melhor.
LLMs como solução alternativa para a documentação da Apple
- Muitos comentadores dizem que o ChatGPT e ferramentas semelhantes agora são sua principal forma de aprender APIs da Apple, especialmente SwiftUI, macOS e frameworks do iOS.
- As LLMs são elogiadas por revelar rapidamente padrões, truques de casos-limite e exemplos ausentes que a documentação da Apple não fornece.
- Alguns apontam limitações para bases de código proprietárias/internas, nas quais a segurança impede colar código em LLMs; ferramentas voltadas para empresas são mencionadas como uma possível solução.
Situação atual da documentação da Apple
- Amplamente percebida como escassa, pobre em exemplos e frequentemente omitindo detalhes críticos de comportamento (por exemplo, cabeçalhos de rede, comportamento de UIPickerView, views de tabela/stack).
- A documentação frequentemente empurra conhecimentos importantes para vídeos da WWDC, o que muitos consideram um formato de referência inaceitável, especialmente porque vídeos antigos desaparecem.
- Alguns dizem que a documentação e os tutoriais de SwiftUI são “maravilhosos” pelos padrões da Apple, mas ainda incompletos para casos de uso fora do caminho feliz.
Declínio histórico e causas (conforme discutido)
- Vários lembram que a documentação antiga de Objective-C / Cocoa e materiais da era “Inside Macintosh” eram exemplares, com explicações conceituais profundas e exemplos.
- O declínio é atribuído no fio a: cadência anual de lançamentos de SO, trilhas duplas de Swift/Objective-C, falta de redatores técnicos dedicados e liderança que não prioriza a qualidade da documentação.
- Outros argumentam que ampliar equipes de documentação não é trivial: bons redatores de documentação precisam ser desenvolvedores fortes, são difíceis de contratar e muitas vezes são subvalorizados e mal remunerados.
Design de API, POO e capacidade de descoberta
- Reclamações sobre designs de POO “desnecessariamente complicados” e herança profunda (por exemplo, NSOpenPanel herdando de NSSavePanel, componentes do UIKit), que tornam o comportamento não óbvio sem percorrer hierarquias de classes.
- Alguns sustentam que isso é um problema do usuário: quem usa um framework orientado a objetos deve esperar navegar pela herança por meio da IDE e das classes-pai.
- Outros contrapõem que uma boa documentação deve expor o comportamento herdado, fornecer exemplos e ensinar conceitos em vez de assumir conhecimento prévio da plataforma.
Documentação vs. futuro com LLMs
- Uma corrente argumenta que a documentação tradicional, abrangente e escrita por humanos continua sendo essencial (citando a biblioteca padrão de Go como um modelo positivo).
- Outra prevê que a documentação vai migrar para tutoriais e anotações acessíveis por LLMs, com LLMs gerando respostas em vez de humanos escreverem referências exaustivas.
- Há preocupação de que, à medida que as LLMs “se bastem”, o incentivo para investir em documentação oficial de alta qualidade enfraqueça ainda mais.
Comparações de plataforma e decisões de saída
- Alguns ainda acham a Apple melhor do que Windows ou Android; outros dizem que a documentação ruim e as APIs complexas os levaram a abandonar completamente o desenvolvimento nativo para Apple.
- A documentação do Flutter é apresentada como um forte contraexemplo, com APIs multiplataforma mais claras e material de referência melhor.