Идея, касающуюся структуры документации, которая, на мой взгляд, сможет существенно упростить процесс работы с ней.
Навигация
Предлагаю отказаться от ручного составления оглавлений в наших файлах документации и перейти к их автоматической генерации. Система будет создавать оглавления на основе заголовков второго, третьего и четвертого уровней (h2, h3, h4 и т.д.). Это нововведение позволит достичь следующих целей:
Повысить эффективность поддержания актуальности переводов благодаря автоматизации;
Достигнуть унификации формата текстов, обеспечив единообразие заголовков и ссылок;
Извлечь оглавления в отдельный блок, что предоставит нам возможность их скрывания для пользователей, впервые знакомящихся с документацией.
Данная инициатива не окажет влияния на якорные ссылки, ведущие на другие страницы. Существующие теги для якорей, например:
<a name="generating-migrations"></a>
Останутся нетронутыми и будут функционировать как прежде, сохраняя стабильность перекрёстных ссылок в документации. Переводчику не нужно будет забояться о перекрёстных url и он по-прежнему сможет беззаботно копировать.
Переменные
Кроме того, предлагаю пересмотреть формат внедрения хешей коммитов. Вместо текущего варианта:
git XXXX
----
Я предлагаю использовать более гибкий и информативный формат в стиле YAML, который позволит нам встраивать переменные и дополнительные данные прямо в текст документации:
---
git: XXXX
---
Это позволит нам добавлять ключевые слова, заголовки и другие важные метаданные в формате:
Идея, касающуюся структуры документации, которая, на мой взгляд, сможет существенно упростить процесс работы с ней.
Навигация
Предлагаю отказаться от ручного составления оглавлений в наших файлах документации и перейти к их автоматической генерации. Система будет создавать оглавления на основе заголовков второго, третьего и четвертого уровней (h2, h3, h4 и т.д.). Это нововведение позволит достичь следующих целей:
Данная инициатива не окажет влияния на якорные ссылки, ведущие на другие страницы. Существующие теги для якорей, например:
Останутся нетронутыми и будут функционировать как прежде, сохраняя стабильность перекрёстных ссылок в документации. Переводчику не нужно будет забояться о перекрёстных
urlи он по-прежнему сможет беззаботно копировать.Переменные
Кроме того, предлагаю пересмотреть формат внедрения хешей коммитов. Вместо текущего варианта:
Я предлагаю использовать более гибкий и информативный формат в стиле YAML, который позволит нам встраивать переменные и дополнительные данные прямо в текст документации:
Это позволит нам добавлять ключевые слова, заголовки и другие важные метаданные в формате:
Для наглядной иллюстрации как это выглядит в IDE: