Проект GenPipes

На этой странице содержится подробная информация о проекте технического написания, принятом для участия в Google Season of Docs.

Краткое описание проекта

Организация с открытым исходным кодом:
ГенПайпы
Технический писатель:
шалу
Название проекта:
Настройте документацию GenPipes в разделе «Читать документацию».
Длина проекта:
Стандартная продолжительность (3 месяца)

Описание проекта

Я предлагаю трехэтапный план для достижения цели по настройке документации GenPipes в разделе «Читать документы».

Шаг 1: PoC

  • Просмотрите существующую документацию GenPipes в качестве нового пользователя/исследователя.

    • Выявить недостающую информацию, неточности
    • Предлагайте новые темы документов (при необходимости)
    • Разработать карту информационной архитектуры для целевой аудитории с акцентом на новых пользователей.

    (Примечание. На этом этапе нам также могут понадобиться отзывы наставников GenPipes относительно настройки нового репозитория GitHub, в котором могут размещаться документы genpipes для RTD. Этот репозиторий GitHub можно использовать для импорта всех документов в конвейерах сборки RTD. Для этого может потребоваться понимание Правила репозитория GenPipes и рекомендации по управлению исходными кодами, если таковые имеются, в противном случае можно использовать стандартные, кстати. Также для PoC я могу продемонстрировать образец. Настройка репозитория RTD с использованием моей учетной записи GitHub — например, https://gpdocs.readthedocs.io/en/latest/ — это образец, который я создал для этого предложения)

  • На основе проверки и анализа на предыдущем этапе создайте базовый скелет предлагаемой структуры/индекса документации GenPipes и разместите его на сайте RTD.

    • Это включает в себя создание репозитория GitHub (например, с помощью инструментов Sphinx) и базовых файлов документации.
    • Это также предполагает создание нового содержания, которое учитывает как новых пользователей, так и опытных пользователей для различных разделов/потоков информации.

  • Рассмотрение/получение одобрения на скелет скелета TOC

    На этапе оценки GenPipes GSoD я пытался создать ценность для GenPipes с помощью этого образца, размещенного на RTD. Обратите внимание, что это только для демонстрационных целей, ссылка защищена и еще не опубликована в открытом доступе на RTD. Независимо от того, попаду ли я в шорт-лист, эту демонстрацию можно использовать для запуска усилий GenPipes RTD. Я уже проверил исходники в репозитории c3g/GenPipes GitHub. Наставникам, Роле и Гектору, он понравился во время обсуждения «общего экрана» в Skype ранее, и поэтому я подумал, что GSoD Gods, возможно, тоже захотят это увидеть. На данный момент это скелет скелета, но я планирую обновить его, когда позволит время, до 30 июля.

https://genpipes.readthedocs.io/en/latest/

Шаг 2. Создание набора документации GenPipes Doc v0.9

  • Определите, какие текущие или существующие документы GenPipes можно импортировать, связать или преобразовать в документацию на основе Sphinx/first для размещения на RTD, учитывая сроки GSoD.

  • При необходимости преобразуйте идентифицированные документы в первый формат, создайте новые, где это применимо, повторно используйте все возможное/уместное.

    • Импортируйте этот первоначальный набор документов в ReadTheDocs как доказательство концепции и разместите его там как защищенный репозиторий. Поместите заранее примечание, предлагающее новым пользователям перейти к исходной документации GenPipes до тех пор, пока не будет получено разрешение на проверку/официальное переключение.

  • Обзор/исправление курса/обновление

Шаг 3. Доработка, рассмотрение и публикация первого черновика в RTD.

  • Заполните подробную информацию о предлагаемой новой структуре документации GenPipes в оглавлении GenPipes – добавьте дополнительные документы, помимо первых нескольких (файл Readme GenPipes), концепции, учебные пособия и т. д.

  • Добавьте четкое разграничение в оглавление для обращения к новым пользователям, опытным пользователям GenPipes, разработчикам GenPipes и т. д.

  • Предложите, обсудите рабочий процесс с частичной автоматизацией через RTD (сборки sphinx) о том, как можно поддерживать набор документации GenPipes, редактировать его пользователями и разрешит ли C3G это внешним участникам документации. Это может потребовать создания некоторых рекомендаций для обновлений документов, аналогичных рекомендациям по кодированию. Может потребоваться больше подэтапов. Например, автоматизируйте проверку орфографии перед утверждением PR в документах GenPipes.

Отчет

Наконец, создайте отчет для GSoD на основе опыта, журналов и отзывов наставников.

Другие мысли

В будущем (через 3 месяца), если это применимо, я могу помочь сохранить это для GenPipes на более длительный срок. Или обучайте других, если необходимо, тому же. Мы можем понять это, основываясь на результатах первых трех месяцев.

Кроме того, я бы предложил дополнительную идею предложения по проекту — создание трехстраничного краткого описания GenPipes, которое поможет облегчить адаптацию. Сегодня новому пользователю приходится пройти немало препятствий, прежде чем он сможет начать работу с GenPipes, поскольку документация хороша, но разрознена и не подходит для новых пользователей. Не уверен, что это можно сделать за 3 месяца, но я бы хотел попробовать.

Это же предложение и то, как оно появилось (историю), можно также посмотреть по адресу https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing.