На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- Творческое сообщество
- Технический писатель:
- Нимишнб
- Название проекта:
- Руководство по использованию словарного запаса
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание проекта
Краткое описание проекта
Vocabulary имеет огромный потенциал для использования в качестве основной библиотеки компонентов пользовательского интерфейса для создания веб-сайтов. Что ему нужно, так это надежное, но понятное для непрофессионала практическое руководство. Важная информация для разработчиков, такая как руководства по компонентам, спецификации использования и настройки конфигурации, составляют важную часть любой документации. Это не только побудит существующих пользователей почувствовать, как словарный запас продолжает расти и достигать новых вех, но и будет способствовать использованию словарного запаса в сравнительно новых проектах. Желаемые результаты моего пребывания в качестве стажера заключались бы не только в написании серьезного руководства по использованию уже существующих компонентов, но также в проектировании и разработке домашней страницы (ведущей к интегрированной документации для каждого) для Vocabulary, Vue- Словарь и шрифты.
План проекта
Проблема: Документация является одной из основных причин, определяющих успех той или иной библиотеки с открытым исходным кодом. Главный вопрос, о котором думают разработчики при выборе подходящего технологического стека для создания своих приложений: «Хорошо ли документирована библиотека? Он в хорошем состоянии? Есть ли у него значительная поддержка использования и ошибок?». Это именно те вопросы, которые мы должны задавать себе, реализуя идею этого проекта. С точки зрения разработки программного обеспечения:
Анализ требований: Существует насущная потребность в краткой и консолидированной документации для наших нужд. Отсутствие документации вредит будущим перспективам приложений с открытым исходным кодом и, безусловно, является важным и немаловажным компонентом. Ссылки на эту документацию должны представлять собой привлекательную домашнюю страницу, которая мгновенно захватывает интерес людей. Документация должна быть хорошо организована, обеспечивая тем самым беспрепятственное ее рассмотрение.
Технические характеристики: В зависимости от требований могут быть определены технические характеристики. Содержимое документации может быть сформировано на основе данных, представленных на веб-сайтах CC netlify, а также на основе хорошо известных документов, таких как semantic-ui, scikit-learn, numpy, bootstrap и т. д. Результатом выполнения этой задачи будет требуемая целевая страница. и полные руководства по документации.
Некоторые общие проблемы, связанные со словарем, Vue-словарём и шрифтами на данный момент:
Отсутствие документации; и даже если они есть, их части разбросаны по сайтам netlify. Это не позволяет пользователям, разработчикам или внешним участникам использовать нашу библиотеку.
Чтобы добраться до определенного компонента и скопировать соответствующий ему код, требуются дополнительные клики. Простой поиск в Google чего-то вроде «Словарь CC компонента вкладок» не возвращает нужную информацию. Опция поиска в руководствах по документации значительно улучшит UX.
Немного более текстуально подробное описание компонентов, описывающее неочевидные детали.
Нет возможности запуска в реальном времени. Живой запуск поддерживается различными сайтами, такими как JSFiddle, что позволяет разработчикам получить представление о компоненте, не запуская все приложение, чтобы увидеть его работу.
Решение
Возможны несколько решений. Тем не менее, я коснусь некоторых здесь и представлю свое окончательное решение в заключительной части:
= Использование readthedocs readthedocs — хорошо известное решение для написания документации для библиотек с открытым исходным кодом. Он основан на Sphinx, инструменте документации Python.
Плюсы:
- Широко распространенная форма создания документации, используемая такими организациями, как Ethereum (Solidity).
- Оптимально структурированная документация.
- Бесплатный статический хостинг.
Минусы:
- Отсутствие абсолютного контроля над стилем.
= Использование Sphinx Мы также могли бы использовать Sphinx для части документации, он предоставляет хорошие возможности для всех наших целей.
Плюсы:
- Самый популярный инструмент Python для документации.
- Также имеется поддержка поиска документации.
- CSS по умолчанию может быть заменен пользовательским; некоторый контроль над HTML с использованием файлов .rst.
Минусы:
- Будет включать кодирование на Python и реструктурированный текстовый формат (.rst), что будет отклонением от предлагаемых языков проекта.
= Использование тем Jekyll Темы Jekyll интегрированы в страницы github, и существуют уже существующие шаблоны, которые можно настроить в зависимости от наших потребностей.
Плюсы:
- Готовые темы документации для любых целей.
- CSS и стили по умолчанию могут быть заменены пользовательскими, а также контролировать HTML.
- Извлекает CSS Primer по умолчанию для создания страниц.
- Простая интеграция со страницами GitHub.
Минусы:
- Может не обеспечить лучшее структурирование документации.
= Использование страниц GitHub Стандартные страницы GitHub для создания статического сайта (HTML, CSS, JS).
Плюсы:
- Полный контроль практически над всем, о чем идет речь.
- Максимальная гибкость в выборе планировки, цветов и стилей.
- Простое использование компонентов словаря.
- Простое встраивание фрагментов кода и ссылок для запуска в реальном времени.
Минусы:
- Возможно, это более трудоемкий подход.
= Использование Haroopad Вместо этого это альтернативное решение для уценки.
Плюсы:
- Это потребует минимального сложного кодирования.
- Основное внимание будет уделяться идеальному написанию документации.
Минусы:
- Отсутствие контроля над CSS.
- Может иметь, а может и не иметь лучшую поддержку сообщества.
- Может не поддерживать MDX.
= Использование MKDocs Это дает другое альтернативное решение для уценки.
Плюсы:
- Потребуется минимум сложного кодирования (снова).
- Пишите больше, подход «Меньше кода».
Минусы:
- Отсутствие контроля над CSS.
- Может не иметь лучшей поддержки сообщества.
- Использует питон; в дальнейшем может возникнуть необходимость развернуть экземпляр Amazon S3.
= Использование VueJS +StorybookJS Этот подход обычно используется в Vocabulary и родственных ему репозиториях.
Плюсы:
- Придерживаться технологий, которые гарантированно будут работать нормально, учитывая прошлый опыт работы.
- Знакомство с кодовой базой.
- В этом пространстве нет компетентных технологий.
Минусы:
- Для тех же целей могут присутствовать и более простые варианты.
В заключение я хотел бы думать, что подход, включающий подход VueJS+Storybook (HTML,CSS,JS), кажется наиболее подходящим, учитывая, что мне он тоже нравится. Однако это также будет означать, что мы не будем полностью отказываться от разработки этого приложения. Также было бы довольно просто использовать компоненты CC-Vocabulary. Однако, чтобы определиться со структурой документации, нам обязательно следует рассмотреть способ разделения контента по подзаголовкам в документации readthedocs. Меня впечатлил веб-сайт Semantic-UI (который использует StoryBook), поскольку он имеет минималистичный вид, и можно легко узнать, чего он хочет, всего за несколько кликов. Помимо Semantic-UI, я также изучил Material Design, Primer, Bootstrap, Carbon Design и т. д., которые можно использовать в качестве руководств по стилю пользовательского интерфейса и систем проектирования в своей работе. Мы также можем поискать готовые темы документации Jekyll для вдохновения.