Сайт проекта и документация: что там есть, а чего нет

Сайт проекта своих файлов не хранит: он ведёт на те же выпуски. Это не недостаток, а полезное свойство — сверять адрес удобнее, когда источник ровно один.

Три адреса проекта

Файлы лежат только в репозиториях со сборками и в магазинах — полный список мест.

Почему сайт не источник файла

Это выглядит как придирка, но различие рабочее. Когда сайт раздаёт файлы сам, проверять приходится два адреса: сайт и хранилище. Когда сайт только ведёт на выпуски, источник остаётся один, и вопрос «а тот ли это файл» сводится к одному имени владельца в адресе — как это проверяют.

Второе следствие: любой сайт, который раздаёт файл Happ у себя, по определению не является сайтом проекта. Это может быть добросовестный каталог программ, а может быть что угодно ещё — про зеркала и копии.

Чем полезна документация

В ней лежит то, чего нет ни в одном стороннем справочнике: официальные формулировки сообщений приложения. Если Happ показал непонятную строку, поиск по документации обычно точнее поиска в интернете — там та же формулировка, что и на экране.

• Описание настроек и того, что каждая из них делает;
• Тексты ошибок и сообщений — в том виде, в каком их пишет само приложение;
• Разбор форматов подписки и того, как приложение их читает — что такое ссылка-подписка;
• Открытый исходник всей документации: видно, кто и когда её правил.

Как отличить сайт проекта от справочника

Справочников по приложению много — этот в их числе. Разница не в оформлении и не в тоне, а в двух вещах, которые видно сразу.

Мы относимся ко второй колонке и не делаем вид, что к первой: об этом написано в разделе о сайте.

Зачем нужен сайт, если файлов на нём нет

Вопрос резонный, и ответ у него практический. Сайт проекта решает две задачи, которые репозиторий решает плохо: даёт человеческое описание приложения и служит единой точкой, с которой видны все места выдачи сразу.

Для проверки это удобно: если вы сомневаетесь, относится ли найденная карточка или репозиторий к проекту, посмотрите, ведёт ли туда сайт. Обратное тоже верно — место выдачи, на которое сайт не ссылается, официальным считать не стоит.

Как искать, чтобы попасть на источник

Поиск по названию приложения выдаёт десятки страниц, и первые места в нём занимают не источники, а справочники и каталоги — просто потому, что их больше и они лучше приспособлены к поиску.

Рабочий приём — искать не приложение, а конкретный адрес: имя владельца репозитория или точное имя файла. Такой запрос выводит на источник почти всегда, потому что чужие сайты редко повторяют эти строки без изменений. Ещё надёжнее — не искать вовсе и держать постоянный адрес файла в закладках.

Что искать в документации в первую очередь

Документация большая, и заходить в неё «почитать» бессмысленно. Три случая, когда она реально экономит время.

• Приложение показало непонятную строку. Формулировки сообщений в документации те же, что на экране, — поиск по точной фразе работает лучше, чем поиск в интернете;
• Не понимаете, что делает настройка. Особенно это касается маршрутизации: какие приложения идут через сервер, а какие мимо;
• Разбираетесь, как приложение читает подписку. Полезно, когда строка добавляется, а серверы не приходят (разбор симптомов).

Исходник документации открыт, поэтому у любой её страницы видно, когда её последний раз правили, — редкая роскошь для справочных материалов.

Почему справочников по приложению так много

У приложения миллионы пользователей и всего несколько собственных страниц, написанных сухо и по-английски. Разницу заполняют сторонние площадки — обзоры, каталоги, справочники и продавцы доступа. Это естественный процесс, а не заговор.

Проблема не в количестве, а в том, что среди них трудно отличить полезное от вредного: выглядят все примерно одинаково. Рабочий признак — куда ведёт кнопка скачивания. Площадка, отдающая файл со своего адреса, встаёт между вами и проектом, и проверить её нечем (разбор).

Как пользоваться сайтом проекта на практике

Держать его в закладках имеет смысл ровно для одной задачи — проверить, не изменились ли адреса. Раз в полгода это разумно: проекты переезжают, магазинные карточки появляются и исчезают.

Для всего остального он не нужен: файл берётся по постоянному адресу, объяснения — здесь, а документация ищется поиском по точной формулировке, а не листанием разделов.