Документация
Документация
Документация Foundation — не брошюра, к которой приложена инструкция. Это само знание о том, как эксплуатировать программное обеспечение, и оно опубликовано в том же репозитории, что и код, который описывает. Поэтому описание и реализация не могут разойтись, и всё это останется у вас при любом развитии событий.
Здесь всё открыто
Прежде чем решать, подходит ли Foundation вашему проекту, можно прочитать всё. Аккаунт не нужен, переписка с кем-либо тоже: по шагам можно идти в своём темпе. Закрытых разделов нет, как нет и версии, доступной только клиентам.
Это часть замысла. Платформа действительно пригодна для повторного использования тогда, когда знания, нужные для внедрения, настройки, развёртывания и поддержания сайта в рабочем состоянии, переходят вместе с программным обеспечением, а не остаются у того, кто её написал.
Руководства по эксплуатации
Руководств восемь, и каждое является опорой по своей теме. Все они написаны для человека, который видит Foundation впервые.
- Adoption — создание нового проекта на Foundation
Как начать новый проект с фиксированного выпуска Foundation, чтобы платформа и знания об эксплуатации были с вами с самого начала.
- Deployment — публикация проверенного сайта
Путь до публикации сайта и важные проверки перед ней, включая работы, которые может выполнить только владелец аккаунта: домен и DNS.
- Foundation Upgrade — переход на новый выпуск
Как принять новый выпуск Foundation и как разделение файлов платформы и файлов сайта защищает настройки, контент, ресурсы и бренд.
- Site customization — настройка сайта
Руководство для того, кто работает с сайтом: что именно меняют, как добавить язык и где на самом деле находится идентичность сайта.
- Branding and assets — бренд и ресурсы
Роль ресурсов, которые сайт заменяет своими, и порядок замены каждого из них.
- Content management — управление контентом
Как страницы, навигация и тексты сайта хранятся файлами, как их добавлять и изменять.
- Validation — проверки перед приёмкой изменения
Что проверяется до того, как изменение принимают, и как запустить эти проверки самостоятельно.
- Troubleshooting — как сузить причину
Первые шаги, когда что-то не работает: от вывода при развёртывании до страниц, которые не отображаются.
Для чтения не нужны ни аккаунт, ни разрешение
Руководства написаны так, что их может прочитать и выполнить любой. Регистрации и подписки нет, закрытых для посторонних разделов тоже. Есть только одно, чего документация сделать не может: выполнить за вас работы, требующие доступа к аккаунту, например настройку записей DNS у регистратора. Это делает владелец аккаунта.
С чего начать
Порядок, при котором времени тратится меньше всего. Для каждого шага указано руководство, где он описан.
Прочитать, что такое Foundation
README в репозитории: что даёт платформа, что в неё сознательно не входит и как выглядит сайт, построенный на ней.
Запустить локально, прежде чем читать дальше
Запустите проект и посмотрите базовый сайт в работе. Час практики отвечает на больше вопросов, чем день чтения описаний.
Решить, как вы будете этим владеть
Один сайт или несколько. Свои аккаунты или работа под ключ. Это решение определяет больше, чем любой другой технический выбор.
Создать свой проект
Руководство Adoption: проект на основе фиксированного выпуска Foundation, вместе с платформой и знаниями об эксплуатации.
Сделать сайт своим
Site customization и Branding and assets: идентичность, контент, языки, ресурсы. Не переписывая платформу, а через настройки и файлы.
Опубликовать на своём домене
Руководство Deployment и порядок развёртывания, включая работу с DNS, которую может выполнить только владелец домена.
Поддерживать в рабочем состоянии
Новые выпуски принимают по руководству Foundation Upgrade, а что проверяют перед приёмкой изменения — в Validation.
Что руководства предполагают и чего не решают за вас
Руководства написаны для компетентного разработчика, который видит Foundation впервые. Предполагается, что он умеет работать в терминале, запускать менеджер пакетов, редактировать файлы и публиковать веб-приложение у любого провайдера. Опыт написания фреймворков не предполагается, как и того, что перед началом вы прочитаете всю документацию по архитектуре.
Есть и второе предположение: работу выполняете вы. Все шаги написаны для человека, который работает в своём репозитории, со своим аккаунтом хостинга и своим доменом. Там, где нужны действия, доступные только владельцу аккаунта, например доступ к записям DNS у регистратора, это сказано на месте, а не выясняется позже.
Зато руководства не принимают решений за вас. Они объясняют варианты, которые поддерживает платформа, и их последствия, но не указывают, какого провайдера выбрать, сколько языков публиковать и вести ли сайт самостоятельно. Это вопрос дела, а задача документации — сделать этот выбор обоснованным, а не случайным.
И об ограничении стоит сказать заранее: руководства объясняют поведение самой платформы и обязанности того, кто её внедряет. Они не описывают внутреннее устройство сторонних сервисов, к которым подключается сайт, и не собираются этого делать. Если точка подключения ведёт к чужому продукту, опорой становится документация этого продукта.
Документы в корне репозитория
Пять файлов, описывающих сам продукт, а не порядок работы.