На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Язык Джулии
- Технический писатель:
- мкг33
- Название проекта:
- Единая документация научного машинного обучения
- Длина проекта:
- Длительный ход (5 месяцев)
Описание проекта
Я хотел бы поработать над объединением организации SciML, потому что в этой области есть много возможностей для улучшения, и завершение этого проекта, несомненно, принесет немедленную выгоду как программистам Julia, так и активным участникам/сопровождающим SciML. Пакеты, разбросанные по SciML, предлагают некоторые действительно полезные инструменты, но всегда существует опасность, что они могут остаться незамеченными (особенно новичками) просто потому, что пользователь не смог обнаружить пакет и применить его для решения возникшей проблемы.
Это довольно неприятно, учитывая, что основная цель пакетов — охватить широкую аудиторию программистов (как новичков, так и экспертов). Чтобы избежать описанной выше ситуации, я предлагаю тщательно пересмотреть «главную страницу» документации SciML и создать своего рода хаб, который пользователи могли бы использовать для просмотра связанных пакетов и изучения растущей экосистемы. Он также может послужить ценным ориентиром для более опытных пользователей и позволить им работать более эффективно.
Прежде всего, существующая документация всех отдельных пакетов нуждается в доработке по самым основным стилистическим вопросам (таким как орфография, пунктуация, грамматика и т. д.). Чтобы обеспечить стилистическую последовательность, SciML должен иметь конкретное руководство по стилю (необходимое для внесения ретроспективных изменений и для использования в будущем). Начинать с нуля было бы пустой тратой времени. Вместо этого он должен основываться на существующих соглашениях Julia и включать новые решения для проблем, специфичных для SciML.
Как только руководство по стилю будет завершено, я намерен пересмотреть текущую документацию на втором этапе проекта. Благодаря этому документация будет выглядеть более профессионально и стабильно. Я уже создал несколько запросов на включение, которые иллюстрируют мой подход к этой задаче. На этом этапе я также намерен разработать (и внедрить) эффективную систему цитирования. Самой первой задачей будет обновление устаревшей страницы цитат.
Третий этап, возможно, самый важный, будет включать разработку дорожной карты SciML, в которой будет подчеркнуто взаимодействие между разрозненными пакетами. Чем сильнее связь между двумя пакетами (в отношении проблемы или самого кода), тем ближе они должны отображаться в списке «см. также». Я предлагаю создать два рекомендательных ключа: один для сходства кода и один для схожести проблем. Таким образом, пользователи смогут гораздо быстрее находить другие потенциально полезные пакеты, чем утомительно просматривать соответствующие репозитории и документацию. Вместо того, чтобы перечислять все возможные связи между пакетами, я бы предпочел сосредоточиться на более крупных и попытаться представить их связи с меньшими пакетами (этот метод также будет распространен на обновление руководств, где должна быть указана связь с другим пакетом). Такой подход гарантирует, что списки «см. также» будут информативными и не будут содержать исчерпывающего перечисления комбинаций пакетов.