Текущая фаза:
Программа «Сезон документации 2021» завершилась 14 декабря 2021 г. См. график .
Используйте этот пример, чтобы создать собственный отчет о тематическом исследовании.
PicklePlus: документирование инструмента для публикации GloriousPickle
Организация или проект: ссылка Glorious Pickle на основной сайт вашей организации или проекта здесь.
Описание организации: GloriousPickle (текущая версия 1.2.3, первый выпуск в 2009 году) — это библиотека, лицензированная MIT, позволяющая легко рассчитать идеальное соотношение соли, сахара, уксуса и специй для всех возможных маринованных овощей в количествах, варьирующихся от одного отдельного молодых огурцов до контейнеров с редисом.
Авторы: по желанию: укажите авторов тематического исследования; используйте имена пользователей, если требуется
Постановка задачи/Резюме предложения
Какую проблему вы пытались решить с помощью новой или улучшенной документации? Если возможно, дайте ссылку на страницу предложения на сайте вашего проекта.
Добавление ингредиентов в базу данных ингредиентов инструмента GloriousPickle занимает много времени и сложно, а у инструмента нет хорошей документации. Многие потенциальные участники не имеют опыта использования git или создания запросов на включение. Это означает, что у GloriousPickle есть серьезные пробелы в наших данных об ингредиентах, что делает наш инструмент менее полезным. Улучшая документацию по добавлению новых ингредиентов, мы надеемся привлечь новых участников и увеличить количество маринования!
Описание проекта
Создание предложения
Как вы пришли к своему предложению Season of Docs? Какой процесс использовала ваша организация для принятия решения по идее? Как вы собирали и учитывали обратную связь?
GloriousPickle PickleDocs SIG узнал о программе Season of Docs из твита из офиса программ открытого исходного кода Google. SIG обсудила программу на своих встречах, проводимых раз в две недели, и согласилась подготовить предложение. Два члена SIG (@KimChiCook и @Dillicious) вызвались поработать над проектом предложения для рассмотрения на следующем собрании.
После того как группа PickleDocs SIG согласовала проект предложения, в адрес более широкого проекта было отправлено электронное письмо с просьбой оставить отзыв. Четырнадцать членов сообщества высказали свои отзывы, в том числе @GloriousPicklePat, сопровождающий API добавления ингредиентов. @GloriousPicklePat вызвался быть полезным во время программы.
После обсуждения и учета полученных отзывов предложение было отправлено на голосование в Руководящий комитет проекта GloriousPickle. Все пять членов GPPSC проголосовали +1 за подачу предложения и заявки, а @VinegarViv согласился помочь в создании открытой коллективной учетной записи, необходимой для участия в программе и контроля платежей.
Бюджет
Включите небольшой раздел о своем бюджете. Как вы оценили работу? Были ли непредвиденные расходы? В итоге вы потратили меньше суммы гранта? Были ли у вас другие средства помимо Season of Docs, которые вы могли использовать?
Два члена GloriousPickle PickleDocs SIG работали техническими писателями (один в Европе и один в Аргентине). Они помогли нам оценить работу и найти схожие бюджеты проектов, сравнив работу по проекту предложения, которую они проделали раньше. У нас также осталось 1000 долларов США в виде неограниченных спонсорских денег от нашего съезда PicklePals 2019 года, которые мы выделили на проект.
Непредвиденные расходы заключались в том, чтобы помочь нашему техническому писателю арендовать точку доступа Wi-Fi, поскольку они находились в районе, пострадавшем от лесных пожаров, и потеряли доступ в Интернет в своем доме. В итоге мы также разослали участникам меньше футболок, чем планировали, так что это сбалансировалось.
Кроме того, мы решили выплатить компенсацию участнику GloriousPickle, @Piccalily (которая когда-то была профессиональным редактором в своей жизни, не связанной с маринованием), за помощь в редактировании и корректуре документации, созданной техническим писателем.
Участники
Кто работал над этим проектом (используйте имена пользователей по запросу участников)? Как вы нашли и наняли технического писателя? Как вы находили других волонтеров или платных участников? Какие роли у них были? Кто-нибудь бросил? Что вы узнали о рекрутинге, коммуникациях и управлении проектами?
Основная команда, работавшая над этим проектом, состояла из:
- @Dillicious, @KimChiCook (PickleDocs SIG)
- @Piccalily (редактор)
- @GherKen, @VinegarViv (помощь администратора, GPPSC)
- @BBChips, @GloriousPicklePat (эксперты в данной области)
- Сэм Скриб (технический писатель)
Мы нашли Сэма Скриба в списке репозиториев Season of Docs на GitHub . Мы думали, что их опыт (Сэм работал в кулинарном журнале, а также писал документацию для веб-сайтов) хорошо сочетался с нашим проектом. Сэм присоединился к телеконференции PickleDocs SIG, проводимой раз в две недели, и обсудил с нами проект, сделав несколько очень ценных предложений, которые мы включили в предложение. Мы также обратились к двум другим техническим писателям, известным нам через сети наших членов SIG, но ни один из них не был доступен в течение периода действия программы.
Поскольку часовой пояс Сэма пересекался с большинством членов PickleDocs SIG всего на несколько часов, мы разослали на нашем дискуссионном форуме призыв к пиклерам, которые находились в часовом поясе Сэма и были знакомы с процессом добавления ингредиентов. @BBChips вызвался ответить на вопросы Сэма и помочь ему найти других экспертов, если это необходимо. @GloriousPicklePat также вызвался помочь Сэму понять базовую архитектуру инструмента и возможные сообщения об ошибках API, а также предоставил помощь GitHub и git.
К сожалению, в середине программы @VinegarViv пришлось покинуть проект по личным причинам. Член GPPSC @GherKen взял на себя решение административных и платежных вопросов.
После некоторых пропущенных вопросов (GloriousPickle использует бесплатный экземпляр Slack, и иногда обсуждение движется так быстро, что мы теряем разговоры из-за ограничения на скользящий архив) мы узнали, что нам следует хранить список текущих вопросов в общем документе (мы использовали общий документ Google). Док). Члены PickleDocs SIG проверяли его перед каждой встречей и старались получить ответы до ее окончания. Сэм смог связаться с @BBChips напрямую, чтобы задать срочные вопросы.
Мы были очень довольны работой с Сэмом, и Сэм, помимо обновления документации GloriousPickle, сам стал заядлым сборщиком!
Хронология
Дайте краткий обзор графика вашего проекта (укажите предполагаемую дату окончания или промежуточные этапы, если проект продолжается).
Пока мы ждали, пока программа Season of Docs объявит об участвующих организациях, члены PickleDocs SIG провели поиск всех предыдущих работ, которые, по нашему мнению, были бы полезны Сэму. В течение месяца мы нашли некоторые заметки о предыдущих попытках обновить документацию, которая застопорилась, а также проработали части материалов аудита зрелости документации в репозитории Google opendocs .
Как только мы получили хорошие новости о том, что нас выбрали для участия в Сезоне документации 2021 года, Сэм и команда PickleDocs встретились и разработали примерный график:
| Этап | Завершено |
|---|---|
| Обзор аудита документов | 7 мая |
| Журнал трения: 3 варианта использования | 14 мая |
| Просматривайте журналы трений с помощью @GloriousPicklePat и @BBChips, отвечайте на вопросы | 28 мая |
| Первый вариант обновленной документации, вариант использования 1 | 25 июня |
| Вариант использования 1, черновик проверен @GloriousPicklePat и @KimChiCook | 2 июля |
| Первый черновой вариант обновленной документации, вариант использования 2 | 2 июля |
| Проект варианта использования 2 проверен @GloriousPicklePat и @Dillicious | 9 июля |
| Первый вариант обновленной документации, вариант использования 3 | 9 июля |
| Проект варианта использования 3 проверен @Dillicious и @KimChiCook | 16 июля |
| Ответы на все вопросы по всем вариантам использования | 30 июля |
| Большая часть PickleDocs SIG была в отпуске с 1 по 20 августа. | -- |
| Начать тестирование новых документов в сообществе (документы публикуются в виде черновиков на сайте GloriousPickle). | 21 августа |
| Обратная связь по тестированию включена | 10 сентября |
| Редактирование и корректура новых документов | 17 сентября |
| Статус черновика документов удален, документы официально выпущены | 28 сентября |
| Создан процесс обновления документации | 1 ноября |
| Это тематическое исследование создало | 8 ноября |
| Тематическое исследование отправлено | 16 ноября |
В нашем бюджете предложения мы предполагали, что технический писатель будет тратить 10–15 часов в неделю на работу над нашим проектом. Сэм вел учет затраченного времени и в среднем тратил на это 11,5 часов в неделю.
Результаты
Что было создано, обновлено или иным образом изменено? Включите ссылки на опубликованную документацию, если таковая имеется. Были ли в предложении какие-либо результаты, которые не были реализованы? Перечислите их также.
Три основных варианта использования были задокументированы вместе с полными практическими руководствами для пользователей:
Как добавить новый ингредиент в GloriousPickle
Как добавить вариант ингредиента в GloriousPickle
Как обновить или исправить ингредиент в GloriousPickle
Эти руководства также включали новые шаблоны запросов на включение, чтобы упростить процесс внесения изменений.
Кроме того, в ходе проекта Сэм создал небольшой глоссарий терминов Pickle, который они выучили, который также был опубликован на сайте проекта GloriousPickle.
Мы добавили инструкции по обновлению этих практических руководств для пользователей в вики нашего проекта.
Мы включили создание шпаргалки для новичков в GitHub, чтобы помочь им использовать наши процессы и инструменты, но как только мы просмотрели доступные ресурсы, мы смогли вместо этого создать шпаргалку для другого проекта.
Метрики
Какие показатели вы выбрали для измерения успеха проекта? Удалось ли вам собрать эти показатели? Хорошо или плохо коррелировали показатели с результатами, которые вы хотели получить от проекта? Изменились ли ваши показатели после вашего предложения?
В нашем предложении мы предложили два показателя:
- количество запросов на включение ингредиентов, связанных с ингредиентами
- количество запросов на включение от новых участников
За сентябрь (первый полный месяц с момента публикации проекта документации) мы наблюдали рост количества запросов на включение, связанных с ингредиентами, на 5 % (с 20 в августе до 21 в сентябре), а также мы увидели трех новых участников, которые в общей сложности сделали четыре запросы на включение (по сравнению с двумя новыми участниками, которые сделали два запроса на включение в августе). Мы планируем отслеживать эти показатели ежемесячно.
Начиная с 1 января, мы также будем отслеживать количество участников, внесших в общей сложности более трех вкладов, начиная ежеквартально после публикации документации.
Как ни странно, мы считаем, что эта новая документация позволила новым участникам добавлять в базу данных ингредиентов GloriousPickle — один новый участник упомянул в комментарии к своему PR, что они пробовали раньше, но не завершили свое обновление, потому что они этого не сделали. понять процесс.
Анализ
Что прошло хорошо? Что было неожиданным? С какими препятствиями или неудачами вы столкнулись? Считаете ли вы свой проект успешным? Почему или почему нет? (Если еще слишком рано говорить об этом, объясните, когда вы рассчитываете оценить успех своего проекта.)
Мы очень довольны результатом нашего проекта Season of Docs и считаем его успешным. Новая документация понятна и полезна, и мы уже наблюдаем некоторый рост количества запросов на включение, связанных с ингредиентами, а также количества запросов на включение от новых участников.
Мы также были рады тому, что почти все сообщество GloriousPickle приняло участие, предоставив отзывы об исходном предложении и протестировав новую документацию в черновой форме.
Мы столкнулись с несколькими неожиданными препятствиями — мы были благодарны, что лесные пожары в штате Сэма не причинили большего ущерба, чем отключение интернета! Кроме того, нам было жаль потерять @VinegarViv из проекта; мы желаем ей и ее семье всего наилучшего и надеемся вскоре увидеть ее снова.
Пока Сэм не начал работать над документацией, мы не осознавали, сколько терминов и аббревиатур, связанных с маринованием, будет незнакомо человеку, пришедшему в наш проект без опыта маринования. Тем не менее, Сэм взял за правило вести список всех незнакомых терминов и давал им определения на основе собственных исследований и запросов к членам сообщества для объяснений и ссылок. Этот глоссарий по маринованию окажет огромную помощь в привлечении большего числа людей в сообщество маринования в будущем.
Краткое содержание
В 2–4 абзацах обобщите свой опыт работы над проектом. Подчеркните, чему вы научились и что бы вы хотели сделать по-другому в будущем. Какой совет вы бы дали другим проектам, пытающимся решить аналогичную проблему с документацией?
Одним словом, наш опыт был пикантным! Мы достигли результатов в документации, и наши показатели, похоже, соответствуют нашим целям.
Огромная часть успеха этого проекта заключалась в том, насколько нам повезло работать с нашим техническим писателем Сэмом Скрибом. [Я не писал этого — Сэм] Хотя Сэм не имел опыта работы с GitHub или опыта работы с GitHub, им, как опытным техническим писателям, было удобно погружаться в новую предметную область, задавать вопросы и проводить исследования. Сэм быстро усвоил не только наши проектные инструменты (мы используем канбан-доску, чтобы отслеживать работу), но и наши шутки с огурчиками! Мы очень рады, что Сэм подхватил болезнь маринования и что мы «разлили» ее в нашем сообществе.
Мы бы посоветовали другим проектам:
- Пусть ваши предложения будут небольшими и управляемыми. (Изначально мы хотели включить в наше предложение документацию по использованию нашего оценщика с промышленными машинами для периодического травления, но не включили ее только потому, что одна из членов нашего сообщества, активно занимающаяся оборудованием для травления с открытым исходным кодом, собиралась писать свою кандидатскую диссертацию во время программы. .) В итоге у нас оказалось более чем достаточно работы, чтобы занять Сэма!
- Используйте свои связи при поиске технического писателя. Попросите каждого в вашем сообществе дать рекомендации. Хотя мы нашли Сэма во время сезона документации на GitHub, мы чувствовали себя уверенно, работая с ними, поскольку поговорили с несколькими людьми во время периода подачи заявок.
- Добро пожаловать в ваше сообщество технического писателя! Сэм сообщил нам, что восторженное отношение GloriousPicklers позволило легко задавать вопросы.
- Помогите своему техническому писателю получить навыки работы с открытым исходным кодом. Сэм никогда раньше не использовал git, но, прочитав несколько руководств, они быстро освоились. Поначалу Сэм беспокоился о том, сколько отзывов они могут получить от сообщества и как их учесть, но модель «грубого консенсуса» нашего сообщества ( «консенсус достигается, когда все проблемы рассматриваются, но не обязательно учитываются» ) вселила в Сэма уверенность в своих силах. реагирование на критику, используя свой опыт технического письма.
Приложение
Если у вас есть другие материалы, на которые вы хотели бы дать ссылку (например, если вы заключили контракт на работу со своим техническим писателем, которым хотите поделиться, или шаблоны для вашего проекта документации, или другие открытые ресурсы документации, вы можете список и ссылку на них здесь). Приложение также является хорошим местом для размещения ссылок на любые инструменты документации или ресурсы, которые вы использовали, или местом для выражения благодарности или признательности, которые могут не вписаться в разделы выше.
Благодарности
Наша команда хотела бы выразить признательность следующим людям и вещам:
- @Dillicious хотела бы поблагодарить своего партнера, а также низкокачественное хип-хоп радио.
- @KimChiCook хотел бы поблагодарить своего 할머니 за то, что он научил его мариновать.
- @Piccalily хотел бы поблагодарить Чикагское руководство по стилю онлайн.
- @GherKen хотел бы поблагодарить троих своих детей за то, что они съели все соленые огурцы, которые он смог приготовить.
- @VinegarViv хотела бы поблагодарить остальную команду за то, что они согласились с ее уходом.
- @BBChips хотела бы поблагодарить лучшую доступную еду без маринования — Tunnock’s Caramel Wafers.
- @GloriousPicklePat хотел бы поблагодарить компанию PickleDocs SIG за участие в этом проекте.
- Сэм Скриб хотел бы поблагодарить все сообщество GloriousPickle, но особенно пиклеров, которые прислали им банки для консервирования во время нехватки банок летом 2021 года, положив им начало пути к множеству вкусных соленых огурцов!