Шаблоны страниц
Каркасы, по которым пишутся страницы, и карта того, какие разделы может заполнять сервис, а какие — только человек.
Это служебный раздел. Читателю документации он не нужен.
Два типа страниц
Разделение не косметическое. Фундамент отвечает на вопрос «почему так везде» и пишется человеком почти целиком. Компонент отвечает на вопрос «как устроена эта штука», и шестнадцать его разделов из двадцати — данные из контракта, которые сервис может держать свежими сам.
Что из этого следует для интеграции
| Разделов всего | 17 | ~20 на три страницы |
| Заполняет сервис | 3 | 16 |
| Пишет человек | 14 | 4 |
У фундамента сервис считает по контрактам только «Где встречается» и числа в «Состоянии». У компонента — почти всё, кроме «Когда использовать / не использовать», подписей к картинкам и доступности сверх виброотклика.
Подробные таблицы соответствия — на страницах шаблонов.
Живой образец
Масштаб типографики написан по шаблону фундамента целиком. Смотреть на него полезнее, чем на пустой каркас.
Страницы компонента по новому шаблону пока нет — три страницы на компонент означают переделку генератора, и это отдельный разговор.
Правила письма
Одни и те же для обоих типов:
- Одно правило — одно предложение. Три правила в абзаце — три пункта списка.
- Правило говорит, что делать или чего не делать. «Следует учитывать» — не правило.
- Три и больше однотипных пунктов — таблица, а не проза.
- Предложение, которое только объявляет следующее («Ниже рассмотрим…»), вычёркивается.
- Величина — числом и токеном.
space-05, а не «достаточный отступ». - Неизвестное — в раздел «Чего мы не знаем», а не оговоркой внутри фразы.
- Ни YAML, ни устройства контрактов, ни слов формата. Это подробности реализации.
- Пустых разделов не держим. Нечего написать — раздел удаляется.