На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.
Краткое описание проекта
- Организация с открытым исходным кодом:
- gRPC-шлюз
- Технический писатель:
- Ямраджив
- Название проекта:
- Рефакторинг существующего сайта документации gRPC-Gateway
- Длина проекта:
- Стандартная продолжительность (3 месяца)
Описание Проекта
АБСТРАКТНЫЙ:
Сайт пользовательской документации предназначен для того, чтобы помочь конечным пользователям использовать продукт или услугу. Хороший сайт пользовательской документации очень важен, поскольку он дает пользователям возможность узнать, как использовать программное обеспечение, его функции, советы и рекомендации, а также решать распространенные проблемы, возникающие при использовании программного обеспечения. Это также снижает стоимость поддержки и является частью фирменного стиля продукта. Хороший сайт пользовательской документации — это признак здоровья продукта и команды разработчиков. Без хорошего сайта пользовательской документации пользователь может не знать, как эффективно и результативно выполнять вышеуказанные действия. Сайт пользовательской документации может сыграть решающую роль в обеспечении успеха продукта, потому что отличная коммуникация есть и всегда будет в основе любого бизнеса или продукта, а отличная документация просто берет эту коммуникацию и помещает ее в управляемую структуру, к которой каждый может получить доступ для достижения успеха.
На момент написания этой статьи репозиторий gRPC-Gateway был разветвлен примерно 1200 раз, и 184 человека внесли свой вклад в этот репозиторий. Это показывает, что многие люди во всем мире используют gRPC-Gateway и, возможно, захотят прочитать его пользователя. документация с инструкциями по использованию gRPC-шлюза. Однако сайт пользовательской документации и документации gRPC-Gateway в настоящее время устарел и неполн, и сообщество gRPC-Gateway хочет использовать этот проект для рефакторинга существующего сайта документации и улучшения своего сайта документации, чтобы обеспечить конечным пользователям удобство использования gRPC-шлюз.
ТЕКУЩЕЕ СОСТОЯНИЕ:
В настоящее время у сайта документации gRPC-Gateway есть две основные проблемы:
• Первая проблема — плохой и устаревший веб-сайт документации. Стиль и структура сайта, а также используемая тема устарели, неполны, на них трудно ориентироваться или найти информацию, они не охватывают многие функции хорошего веб-сайта документации. Рефакторинг существующего сайта документации gRPC-Gateway будет включать в себя стилизацию веб-сайта, добавление таких функций, как поиск документов и т. д., улучшение пользовательского интерфейса веб-сайта, организацию учебных пособий и примеров на соответствующей боковой панели, а также обновление существующих блок-схем и изображений путем разработки нового и т. д. Это будет моей основной целью, и моя работа будет в большей степени основана на стилизации и реструктуризации существующего сайта Документов.
• Вторая проблема: необходимо провести рефакторинг существующей документации, учебных пособий, примеров и т. д. gRPC-Gateway, что можно сделать, удалив типографские и грамматические ошибки в файлах, правильно выровняв фрагменты Go и реорганизовав фрагменты Go в соответствии с Gofmt. форматы. Кроме того, если это так, мы можем добавить дополнительную документацию, учебные пособия и примеры, если это необходимо, или мы можем повторно использовать существующие файлы после их рефакторинга. Это моя второстепенная цель, и я займусь этим после того, как выполню свою основную задачу, т. е. стилизацию и реструктуризацию существующего сайта Документов.
ПОЧЕМУ МОЙ ПРЕДЛАГАЕМЫЙ САЙТ ДОКУМЕНТОВ УЛУЧШЕН ПО СВЕДЕНИЮ?
Предлагаемый веб-сайт с пользовательской документацией будет структурирован так, чтобы его можно было улучшить и обеспечить эффективность, последовательность и спокойствие для конечного пользователя. Это улучшит внешний вид, а пользовательский интерфейс с хорошо стилизованными разделами и функциями будет содержать письменные руководства и связанные с ними блок-схемы и изображения.
Документация gRPC-Gateway содержит хорошее описание метода и примера. Но он по-прежнему использует старую тему Jekyll, и в наши дни у нас есть лучшие темы Jekyll SSG (Static Site Generator). Кроме того, существует необходимость реструктуризации страниц и повышения их полезности для пользователей за счет добавления новых примеров и учебных пособий, а также обновления и переписывания предыдущего содержимого.
СТРУКТУРА И ДОРОЖНАЯ КАРТА ПРЕДЛАГАЕМЫХ ЦЕЛЕЙ И ИДЕЙ:
ОСНОВНАЯ ЦЕЛЬ ЭТОГО ПРОЕКТА:-
Вышеуказанные цели и идеи могут быть реализованы следующими способами:
Смена текущей темы Jekyll на более качественную и надежную. Причина повторного использования тем Jekyll заключается в том, что сопровождающим будет легко внести свой вклад и понять рабочий процесс проекта, поскольку они уже знают о существующей структуре и теме Jekyll, которая похожа на новую тему Jekyll.
Изучив различные темы Jekyll в Интернете, я нашел этот https://idratherbewriting.com/documentation-theme-jekyll/ набор тем, который лучше всего подходит для сайта документации gRPC-Gateway из-за следующей особенности:
• Markdown: - Чтобы техническим писателям не приходилось беспокоиться об установке. Они могут просто писать в файле .md. Любой может нажать кнопку редактирования, отображаемую на веб-сайте (новая функция), и внести свой вклад (отредактировать/предложить изменения для страницы в GitHub), чтобы сделать ее лучше. Это побудит пользователей добавлять новый контент или редактировать контент для его улучшения.
• Поиск документации: — У пользователя должно быть окно поиска, чтобы он мог легко и быстро найти соответствующее содержимое.
• Раздел комментариев: - Пользователь может иметь возможность комментировать и делиться своими мнениями о сообщениях и учебных пособиях. Они могут читать мнения других людей о проектной документации.
• Новые примечания к выпуску и блоги: Веб-сайт должен обновляться новыми сообщениями в блогах и новостями о текущих разработках и планах развития. Таким образом, на целевой странице должен присутствовать вид блогинга.
• Быстрая разработка: большинство платформ SSG (Static Site Generator) работают на сервере, и изменения в файле немедленно отражаются в пользовательском интерфейсе. Кроме того, процесс развертывания и сборки должен быть простым. В будущем, если мы захотим изменить структуру, мы используем. Тогда это должно быть легко. Большинство фреймворков поддерживают запись в формате Markdown, поэтому достаточно просто переместить файлы .md и внести несколько изменений.
Здесь я разделяю существующие страницы веб-сайта на новые разделы и страницы:
• Целевая страница:-
Целевая страница должна указывать на основные функции gRPC-Gateway.
- Начало работы с gRPC-Gateway (перенаправление к руководству пользователя)
- Простая инструкция по установке (краткие команды)
- Зачем использовать gRPC-шлюз
- Проект с использованием gRPC-шлюза
Таким образом, основная идея заключается в том, чтобы вместо того, чтобы писать длинное описание, отобразить основные моменты на целевой странице и предоставить ссылку для перехода к подробной информации.
• Страница руководства пользователя gRPC-шлюза: -
- Инструкция по установке.
- Быстрый старт с gRPC-Gateway.
• Страница руководства разработчика gRPC-шлюза: -
Руководство по разработке, руководство по участию, настройка Git, Кодекс поведения, настройка документации, рабочий процесс разработки и т. д. указывают на похожие страницы внутри. Поэтому необходим рефакторинг и перестановка всех файлов. Главная страница разработки должна содержать все эти страницы, и на каждом этапе будет создаваться гиперссылка.
• О странице gRPC-шлюза: -
Список всех участников должен присутствовать в разделах команды. Быстрые ссылки и примечания к выпуску. Будут добавлены последние блоги, чтобы привлечь пользователей и заставить их прочитать текущие новости gRPC-Gateway.
• Блоги, примечания к выпуску и страница учебных пособий: -
Я считаю, что на этом сайте должна быть возможность ведения блога. Таким образом, новости и релизы можно легко передавать. Страница руководства будет содержать несколько популярных докладов и статей, в которых разъясняются API и концепции gRPC-Gateway. Участники могут добавлять ссылки на свои учебные пособия на страницу учебных пособий.
После выполнения вышеуказанной задачи обновите те же изменения в ветке v2 и сравняйте ее с основной веткой gRPC-Gateway.
ВТОРИЧНАЯ ЦЕЛЬ ЭТОГО ПРОЕКТА: -
Необходимо внести и другие изменения, чтобы сделать документацию gRPC-Gateway более надежной и читабельной:
• Исправление грамматических, типографских ошибок, а также организация и выравнивание ссылок и сообщений на сайте по всем существующим файлам gRPC-Gateway.
• Добавление дополнительной документации и контента при необходимости в gRPC-Gateway, поскольку большинство функций имеют очень краткую документацию, например, в разделе «Документация» сайта по AWS, «История и использование» и т. д.
• Рефакторинг Go фрагментов gRPC-Gateway в соответствии с форматами Gofmt.
После выполнения вышеуказанной задачи обновите те же изменения в ветке v2 и сравняйте ее с основной веткой gRPC-Gateway.
ПОЧЕМУ Я ПОДХОДЮ ДЛЯ ЭТОГО ПРОЕКТА:
Я считаю, что я подходящий человек для этого проекта, потому что:
• У меня есть опыт улучшения документации организаций, и я могу использовать любую систему контроля версий, поэтому выполнение команд на GitHub не будет проблемой. • Более того, меня вдохновляет работа над проектами, которые приносят пользу людям. Я считаю, что если вы хотите, чтобы кто-то сделал что-то максимально эффективно, вы это документируете. Документируя свои процессы, вы обеспечиваете эффективность, последовательность и спокойствие для всех участников. • Я знаком с рабочим процессом и кодовой базой gRPC-Gateway, так как участвую в gRPC-Gateway последние два месяца и получил 11 объединенных PR.