[Перевод] Об ужасной документации Apple
В последние год-два я пришёл к осознанию того, что основной преградой к выполнению моей работы является документация. Или, если конкретнее, откровенный дефицит документации, предоставляемой Apple для своих платформ.
Apple предоставляет разработчикам набор инструментов — API, позволяющий нам создавать приложения для iOS, iPadOS, macOS и tvOS. Во многих случаях разобраться в том, как пользоваться этими API, достаточно просто. Как отвёртку можно использовать очень немногими способами, так и во многих случаях есть только один очевидный способ применения API.
Однако, в то время, как пользователи справедливо требуют всё более сложных и изощрённых приложений, API тоже часто должны становиться всё более изощрёнными и сложными. Внезапно оказывается, что кроме простых отвёрток и молотков у тебя уже появляется электроинструмент и сложные пилы, и всё оказывается намного более хлопотным, чем было раньше.
Когда покупаешь настоящие инструменты, то ожидаешь получить с ними и руководство пользователя, описывающее способ применения только что купленного инструмента. Приблизительная аналогия в некоторой степени существует и для API — большинство владельцев платформ предоставляют документацию. По сути, это «руководство пользователя» API.
В течение многих лет документация Apple была довольно плохой. За последнюю пару лет она прошла этапы «плохая → ужасная → отвратительная → постыдная». Слишком уж часто бывает, что при изучении того, как делать что-то новое и пользоваться незнакомым мне API, меня загоняют в тупик эти три пугающих слова:
No overview available.
Таким образом Apple говорит: «Пошёл ты, разбирайся сам».
Ситуация с No overview available настолько плоха, что популярный ресурс по Apple (который сам по себе, наверно, и не нужен был бы в идеальной ситуации), использовал это словосочетание в качестве названия сайта, подчёркивающего, насколько плоха документация Apple.
Движение прогресса вперёд не улучшает ситуацию. Как указал мне в Твиттере мой друг Адам Суинден после устаревания одних API в новые иногда и не думают добавлять документацию. Оцените разницу между этим API и пришедшим ему на замену.
«No overview available». Пошёл ты, разбирайся сам.
Пару лет назад появились два потрясающих API, связанных с UICollectionView:
Не меньше года, а может и двух, самая лучшая документация по этим новым и важным функциям была спрятана в файлах заголовков. Это отвратительно.
В недавнем подкасте сайта Under the Radar мои приятели Марко и Дэйв продолжили тему перехода Марко на Swift и SwiftUI. В этом эпизоде Марко и Дэйв весьма красноречиво описали ужасающие мучения, которым подвергаются разработчики Apple, пытаясь понять, как пользоваться предоставленными Apple инструментами. В конце поста есть транскрипция подкаста, немного подредактированная для удобства чтения.
Я несколько лет бил в этот барабан. Я понятия не имел, в чём проблема на стороне Apple.
- Отделу документации не дают времени, чтобы отреагировать на новые API? (Я бы в это поверил.)
- Документация не считается обязательным требованием для выпуска API? (Я бы определённо в это поверил.)
- Отдел документации плохо справляется со своей работой? (В этом я сомневаюсь.)
- Отдел документации слишком мал? (Скорее всего.)
- Отделу документации мешают политика и конфликты? (Вероятно.)
В чём бы ни была проблема, её нужно решать. Проблема усугубляется уже несколько лет, и чаша терпения наконец переполнилась.
Транскрипт подкаста Under the Radar
Marco: если изучаешь SwiftUI, то в первую очередь узнаёшь, что существующие обучающие ресурсы довольно ужасны, потому что это очень молодой язык/фреймворк/да и просто образ восприятия вещей. Он настолько молод и так часто меняется (как Swift в своей молодости), что многие туториалы, примеры кода и ответы на Stack Overflow уже просто перестали быть верными. Просто потому, что всё изменилось по сравнению с предыдущим годом. Или потому, что ответ был дан по бете, а в более поздней бете, выпущенной в том же году, изменилось название класса или способ выполнения им какой-то функции.
Сейчас очень ощущается большая потребность поддержки документацией со стороны Apple. Одна из отличных черт PHP в том, что он всегда имел превосходную документацию на своём веб-сайте.
На php.net можно найти любую функцию, а в редакторах добавлены горячие клавиши, поэтому, например, в Textmate я могу нажать ⌃H и появится окно с документацией с сайта php.net о той функции, на которую сейчас установлен мой курсор. У этого языка всегда была отличная документация. На страницах документации по каждой функции языка, а их много, были фрагменты примеров кода. И там есть комментарии! Поэтому даже если пример кода не совсем вам подходит или не отвечает на ваш вопрос, то обычно это делают комментарии.
Именно этого я бы хотел от документации Apple — этих небольших примеров применения, потому что они действительно помогают объяснять, как что-то делается или для чего нужна функция.
Когда мы начали перемещаться на территорию SwiftUI и Combine, а также всех этих высокоуровневых концепций, всё это постепенно становится сложнее — то же самое будет справедливо и когда в Swift реализуют async/await, предположительно через год-два. Становится сложнее понимать многие такие концепции, потому что они очень абстрактны и имеют очень простые названия, по которым трудно сказать, что они делают и как ими пользоваться. Поэтому всем нам приходится отправляться на StackOverflow и в блоги с туториалами, потому что собственная документация (даже если она хотя бы есть, это уже большое событие) настолько лаконична и минималистична, как будто её спроектировал Джон Айв [известный дизайнер-минималист].
Дэйв: … это как большая белая комната…
Марк: Да, это большая белая пустая страница. На ней написано «этот тип нужен вот для этой конкретной вещи», после чего нет никакого контекста; нет примеров, показывающих когда нужно его использовать, как его использовать, нужно ли вызывать его определённым образом, как конструктор.
Эти небольшие фрагменты кода на страницах документации могли бы иметь огромную ценность, как это бывает в случае PHP. Например, «вот пример из четырёх строк того, как использовать эту штуку». И когда я всё это изучаю, мне так не хватает подобного.
Я могу представить, что начинающие так воспринимают почти все элементы программирования; поскольку я такой же новичок в Swift и SwiftUI и во всех концепциях, на которых построен SwiftUI, я впервые за долгое время ощущаю, каково быть начинающим. Мне бы очень пригодилась более качественная документация, я бы выиграл от того, чтобы кто-то (вероятно, Apple) приложил много усилий не только к написанию документации, но и к её обновлению в процессе изменения языка.
Эта проблема возникает, когда молодые языки или фреймворки активно развиваются. Если ты учишься по туториалам в блогах и ответам в StackOverflow, то все они довольно быстро устаревают, как я говорил ранее. Никто в Apple не занимается на полную ставку тем, чтобы все эти туториалы в блогах обновлялись при изменении языка, поэтому чаще всего они не обновлятся. Или некоторые обновляются, некоторые нет, поэтому сложно понять, с чем ты столкнулся.
Но даже в такой ситуации, когда SwiftUI привлёк к себе за последний год такое внимание фанатов языка, по нему всё равно очень мало материалов. Ещё меньше материалов о чём-то более глубоком, чем тривиальные примеры использования. Например, если тебе нужно сделать техническое демо на SwiftUI, в котором должна быть кнопка с изменяющимся состоянием или инкременты числа, то замечательно! О подобном существует миллион постов.
Но рано или поздно у тебя возникает вопрос: «Ладно, а как связать это с остальной частью приложения?» Это настоящее приложение, имеющее реальные потребности в постоянном хранении данных, различных экранах и тому подобном. Как только ты добавляешь сложность реальных приложений, в большинстве подобных туториалов она не рассматривается. Дэйв, однажды мне нужно было адаптировать SwiftUI из этих тривиальных туториалов и выступлений Apple на WWDC к ответам на вопросы «Как мне подключить это к своей базе данных?», «Как подключить это к моей системе скачивания файлов или движку синхронизации?» И таких вопросов было много. Мне кажется, в конечном итоге я с этим разобрался, но, чёрт, всё это нетривиально и неочевидно, к тому же есть множество странных небольших тонкостей.
Дэйв: Я полностью разделяю твою боль. Меня так расстраивает то, что онлайн существует всего пара действительно замечательных ресурсов по SwiftUI. Для меня это Hacking with Swift Пола Хадсона. Примерно 80% моих знаний о SwiftUI взято с его сайта и его видео. Он организовал отличный процесс обучения: видео, в которых показывается один уровень глубже тривиального примера, после которого твои знания становятся тривиальными «плюс немного». Это неполный пример, в нём всё равно много шероховатостей, о которых ты говорил. Я уверен, что продолжу сталкиваться с такими проблемами: ты хочешь сделать что-то чуть большее, чем самое очевидное, но внезапно оказывается, что ты падаешь с обрыва, и остаётся только пожелать себе удачи.
Помню, как в начале весны встретил пару людей, занимающихся обучением в сообществе Apple. Это те люди, которые много выступают на конференциях, проводят воркшопы, и так далее. Они говорили: «Знаете что? Похоже, весь 2020 год мы не сможем ездить на конференции, мы не сможем делать многое. Эй, Apple, в нашем сообществе есть множество очень талантливых преподавателей с кучей свободного времени. Было бы здорово, если бы ты этим воспользовалась».
Печально, что уже почти конец года, а компания, похоже, так этим и не воспользовалась. Непохоже, что она сделала какие-то шаги в этом направлении, чтобы использовать всех этих людей, отлично умеющих объяснять материал и создавать примеры приложений, в том, чтобы проделать эту работу, которая могла бы помочь людям в твоём и моём окружении. Я по-настоящему сочувствую тем, кто приходит в SwiftUI без десятков лет опыта программирования. Если это первое приложение, которое вы изучаете, то в некотором смысле оно довольно лёгкое. Очень примитивное приложение SwiftUI на самом деле проще собрать, наверно, проще, чем большинство примитивных приложений UIKit. Но как только вы начинаете делать что-то большее, всё мгновенно становится очень сложным.
Я также думаю о том, что лучше всего для создания документации подойдут люди, которые создают платформу, но в случае с документацией это сделать сложно. Они могут работать над документацией, чтобы она была доступной в процессе выпуска технологий. Я сочувствую всем, кто обучает разработчиков платформ Apple — когда появляется новый SDK или выпускается новая бета, им приходится не спать по три дня, пытаясь суматошно обновлять все свои материалы и раскрывать возможности новых функций. Они выполняют отличную работу, и я ценю её, но суматохи в ней быть не должно.
Можно было бы сделать так, чтобы отдел документации Apple работал над ней согласованно с людьми, месяцами пишущими API. Поэтому сразу в день их выпуска в документации был бы замечательный набор примеров кода, демонстрирующих способы использования API.
Ты совершенно прав, особенно в отношении SwiftUI — проблема в отсутствии традиционной документации… Если зайти в документацию по Text в SwiftUI, то у типа View есть множество различных модификаторов, которые можно применять к этому View. Их количество, кажется, исчисляется сотнями, если не больше. Однако наличие огромного списка всего того, что можно сделать с Text, ничем не помогает. Мы хотим знать следующее: «Как сделать, чтобы текст выглядел так?», «Что если мне нужен многострочный текст?», «Что если я хочу, чтобы многострочный текст состоял из определённого числа строк, после чего выравнивался по середине?» Реализуя подобные вещи, нам нужны примеры. Я не думаю, что общий список случаев, которые люди используют в реальности, особо широк. Я понимаю вашу боль.
На правах рекламы
Воплощайте любые идеи и проекты с помощью наших VDS с мгновенной активацией на Linux или Windows. Сервер готов к работе через минуту после оплаты!
