Tout sur la documentation Apple : des notes de Woz à DocC et aux agents Xcode

Deux principes coexistent. Le produit grand public ne doit pas exiger un gros manuel pour une action élémentaire, tandis qu’une plateforme développeur ne peut pas grandir sans documentation technique précise et profonde. La documentation devient particulièrement utile quand l’écriture révèle un défaut de l’interface ou de l’API. [A19][A21][A5][A4]

Le relevé du 17 août 2026 s’appuie sur des manuels originaux, Apple Times, des histoires orales du Computer History Museum, des témoignages directs du Macintosh, le Steve Jobs Archive et la documentation Apple et Swift actuelle. Une citation absente n’est pas inventée. [A1][A3][A4][A5][A7][A10][A13][A14][A19][A2]

Apple-1 pouvait se contenter de notes et schémas destinés à un public technique. Apple II élargit le public et impose de rendre consultables les connaissances sur la mémoire, la vidéo, les E/S, la ROM et l’extension de la machine. [A1][A2]

Aucun manifeste fiable de Wozniak sur la documentation n’a été retrouvé. Ses notes et l’Apple II Reference Manual montrent mieux sa contribution : une architecture suffisamment explicitée pour être programmée et étendue par d’autres. [A1][A2]

Chris Espinosa relie le Publications Style Guide aux origines de la cohérence des interfaces Apple. Des explications cohérentes poussaient les applications à adopter elles-mêmes des comportements cohérents. [A4]

Apple Times expose quatre étapes : conception du document, alpha, beta et version finale. La beta était lue par des personnes externes représentatives du public, et les retours pouvaient modifier le manuel comme le produit. [A3]

En 1982, des fichiers Pascal passaient par Script, Qume et Compugraphic avant un paste-up physique avec photos et illustrations. En 1984, Command-Shift-3 pouvait enregistrer l’écran comme document MacPaint. Susan Kare créait des dessins de manuels dans MacPaint tandis que ciseaux et colle restaient encore présents en prépresse. [A3][A7][A8][A6]

Apple Times envisageait déjà en 1982 un apprentissage des fonctions de base sur l’ordinateur lui-même, avec des manuels détaillés pour la profondeur. Onboarding et référence étaient donc séparés bien avant le Web. [A3]

En 1984 Jobs se moque des manuels WordStar de 400 pages. En 2007 il reprend l’idée avec une fonction de téléphone cachée à une page de manuel que personne ne lit. Son objectif vise la découvrabilité, pas la disparition de toute documentation. [A21][A19][A5]

Le manuel Macintosh devait enseigner pointer, click, drag, icon, window, menu et Trash. Dessins de la main, souris et bitmaps liaient le geste physique au changement visible à l’écran. [A7]

Andy Hertzfeld jugeait la documentation développeur cruciale. Les questions très précises de Caroline Rose sur les paramètres et les cas limites révélaient des ambiguïtés et conduisaient parfois à modifier l’API avant de l’expliquer. [A5]

Human Interface Guidelines transforme des comportements en règles communes à des milliers d’applications. Le lien entre Publications Style Guide, HIG 1992 et Apple Style Guide 2026 relie vocabulaire, texte UI et design d’interaction. [A4][A9][A24][A10]

Avec l’expansion des plateformes, trouver l’information devient aussi important que l’écrire. Developer Library et Xcode Documentation Organizer classaient guides, références et exemples, tandis que Quick Help plaçait la référence à côté du symbole dans le code. [A12]

Documentation Archive montre que le retrait des guides s’est fait progressivement. Conserver l’ancien contenu protège la reproductibilité, mais le statut retired, la date et le successeur doivent être évidents pour éviter de confondre histoire et conseil actuel. [A11][A22][A23]

Swift-DocC combine commentaires d’API, articles Markdown et tutorials. Créé pour la documentation interne des SDK Apple, intégré à Xcode puis ouvert, il permet de vérifier liens et structure au moment du build. [A14][A15][A3]

Les pages actuelles proposent du Markdown pour les outils automatisés et les coding agents de Xcode peuvent rechercher la documentation pendant leur travail. Le même savoir sert désormais l’humain, l’IDE et l’agent. [A13][A16][A17][A18]

Susan Prescott présente l’objectif comme la fourniture des meilleurs outils et la réduction des frictions. Apple parle rarement de documentation comme stratégie autonome, car référence, exemples, diagnostics, tutorials et contexte agent font partie de l’expérience développeur. [A17][A18]

Du Publications Style Guide à l’Apple Style Guide 2026, la cohérence de la voix couvre toujours documentation, référence, formation et interfaces. La terminologie reste une propriété du produit. [A4][A9][A10]

La documentation reste proche de l’ingénierie : elle peut influencer l’API, HIG influence les apps, DocC vit avec le code et Xcode fournit le contexte. Apple distingue aussi onboarding, concepts, référence et exemples. [A5][A9][A12][A14]

Une référence de symboles complète ne remplace pas toujours le récit architectural des anciennes Programming Guides. Les pages archivées restent fortes dans la recherche et une fragmentation pensée pour les machines peut nuire à la compréhension humaine. [A11][A13]

Utiliser l’écriture comme test produit, séparer onboarding et référence profonde, standardiser le langage tôt, intégrer les docs au workflow d’ingénierie, marquer clairement les archives et construire un modèle de connaissance commun à l’humain, l’IDE et l’agent. [A5][A10][A11][A14][A17]

Les pages Apple montrent que chaque image répond à une question : schéma pour la structure, dessin au trait pour le geste, screenshot pour l’état, HIG pour le comportement attendu. Un screenshot facile à produire reste coûteux à maintenir. [A1][A7][A9]

Apple est passé des notes d’ingénierie aux manuels testés, aux technical writers capables de modifier l’API, aux règles d’interface, à Xcode, DocC et au Markdown lisible par des agents. Le changement essentiel est le rapprochement continu avec le cycle de vie du produit. [A5][A19][A21]