Un ejemplo concreto de lo que sale mal con la documentación de Apple
La documentación oficial de Apple para las APIs de macOS e iOS es ampliamente criticada por ser superficial, incompleta y difícil de recorrer, especialmente en frameworks más nuevos como SwiftUI. Los desarrolladores describen que pierden horas en tareas básicas y que dependen en su lugar de LLM, blogs de terceros y documentos antiguos archivados de Apple, que eran mucho más detallados; algunos argumentan que esto es consecuencia del ciclo anual de versiones de Apple, el secretismo interno y la baja prioridad dada a la redacción técnica. Otros responden que las APIs son utilizables si entiendes los patrones orientados a objetos y lees con cuidado, pero existe una preocupación general de que la mala documentación perjudica la productividad y está empujando a los desarrolladores hacia herramientas asistidas por IA y plataformas alternativas con mejor documentación.
Los LLM como solución alternativa para la documentación de Apple
- Muchos comentaristas dicen que ChatGPT y herramientas similares ahora son su forma principal de aprender las APIs de Apple, especialmente SwiftUI y los frameworks de macOS e iOS.
- Se elogia a los LLM por mostrar rápidamente patrones, trucos para casos límite y ejemplos que faltan en la documentación de Apple.
- Algunos señalan limitaciones en bases de código propietarias o internas, donde la seguridad impide pegar código en LLM; se mencionan herramientas orientadas a empresas como una posible solución.
Estado actual de la documentación de Apple
- Se percibe ampliamente como escasa, pobre en ejemplos y a menudo omite detalles críticos de comportamiento (p. ej., cabeceras de red, comportamiento de UIPickerView, vistas de tabla/pila).
- A menudo la documentación traslada conocimientos importantes a vídeos de WWDC, lo que muchos consideran un formato de referencia inaceptable, sobre todo porque los vídeos antiguos desaparecen.
- Algunos dicen que la documentación y los tutoriales de SwiftUI son “maravillosos” según los estándares de Apple, pero aun así están incompletos para casos de uso fuera del camino feliz.
Declive histórico y causas (según se discutió)
- Varios recuerdan que la documentación antigua de Objective‑C / Cocoa y los materiales de la época de “Inside Macintosh” eran ejemplares, con explicaciones conceptuales profundas y ejemplos.
- En el hilo, el declive se atribuye a: el ritmo anual de lanzamientos del SO, las dos líneas paralelas de Swift y Objective‑C, la falta de redactores técnicos dedicados y que el liderazgo no prioriza la calidad de la documentación.
- Otros sostienen que escalar equipos de documentación no es trivial: los buenos redactores de documentación deben ser grandes desarrolladores, son difíciles de contratar y a menudo están infravalorados y mal pagados.
Diseño de API, OOP y descubribilidad
- Hay quejas sobre diseños OOP “innecesariamente complicados” y herencia profunda (p. ej., NSOpenPanel heredando de NSSavePanel, componentes de UIKit), que hacen que el comportamiento no sea obvio sin recorrer jerarquías de clases.
- Algunos sostienen que este es un problema del usuario: cualquiera que use un framework OO debería esperar navegar la herencia mediante el IDE y las clases padre.
- Otros responden que una buena documentación debería mostrar el comportamiento heredado, ofrecer ejemplos y enseñar conceptos en lugar de asumir conocimiento previo de la plataforma.
Documentación frente al futuro de los LLM
- Un sector argumenta que la documentación de referencia tradicional, completa y escrita por humanos sigue siendo esencial (citando la biblioteca estándar de Go como un modelo positivo).
- Otro predice que la documentación se desplazará hacia tutoriales y anotaciones accesibles para LLM, y que los LLM generarán respuestas en lugar de que los humanos escriban referencias exhaustivas.
- Existe la preocupación de que, al “bastar” los LLM, el incentivo para invertir en documentación oficial de alta calidad se debilite aún más.
Comparaciones de plataformas y decisiones de abandono
- Algunos consideran que Apple sigue siendo mejor que Windows o Android; otros dicen que la mala documentación y las APIs complejas los empujaron a abandonar por completo el desarrollo nativo para Apple.
- La documentación de Flutter se presenta como un fuerte contraejemplo, con APIs multiplataforma más claras y mejor material de referencia.