В последние год-два я пришёл к осознанию того, что основной преградой к выполнению моей работы является документация. Или, если конкретнее, откровенный дефицит документации, предоставляемой 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. Сервер готов к работе через минуту после оплаты!