Документация для опенсорса: 5 советов новичку

О контрибуции в опенсорс много говорят, и эта фраза часто встречается в рекомендациях начинающим техписателям. Но попробуйте спросить, кто же это делал, и вам ответят единицы. Поэтому у некоторых возникала мысль: а возможно ли это вообще?

Сначала разберемся, что же означает эта фраза? Если говорить кратко, "контрибутить в опенсорс" во вселенной техписателя — это вносить вклад в разработку документации для опенсорсных (свободных) продуктов.

Недавно мы искали желающего, кто может срочно помочь разработчику составить инструкцию к небольшой утилите. Техписатель-джун Полина Клименко согласилась помочь и написала инструкцию для утилиты mdis, которая позволяет "вытаскивать" актуальные примеры из кода.

Мы побеседовали с Полиной и попросили её поделиться опытом создания свободной документации.

— Полина, привет! Расскажи, когда ты впервые столкнулась с выражением "контрибутить в опенсорс", как ты это понимала и представляла себе?

— Прежде всего скажу, что искали начинающего техписа. Я именно таким и являюсь: у меня за плечами пока нет работы или образования в этой сфере. Есть юридическое образование, любовь к выяснятельству и пояснятельству и незаконченный курс по работе с Python. Именно этот курс заложил во мне зерно отчётливого интереса к программированию напару с привычкой почитывать Хабр по дороге на работу или с работы. Если не брать в расчёт теоретические познания в сфере техписательства и чтение профессиональных чатиков, эта работа оказалась для меня первым случаем, когда я приложила свои навыки к документированию.

Если говорить о выражении "контрибутить в опенсорс", то впервые с ним столкнулась в контексте практик программистов. Говорили: если хочешь получить первый опыт разработки и чтобы было что показать работодателю на стадии входа в профессию — делай пет проекты и причащайся к опенсорсным проектам. Желательно, к проектам покрупнее и со вкладом покачественнее. Наверно, в жизнь техписателей такое предложение из общения с программистами и проникло.

Я думала, что контрибуция в опернсорс происходит в отношении продуктов, которые созданы энтузиастами-разработчиками, что оно предполагает изучение проекта и что каждый волен выстраивать и предлагать свои предложения.

— Почему согласилась взяться за такую работу?

— Я только вступаю в профессию, на самый её порожек, поэтому мне очень любопытно сунуть свой нос, куда только можно. А тут подвернулся такой удачный случай! Пожалуй, тут удачно наложились мои необходимость опыта + любопытство + смелость — ещё и в отношении интересного и полезного проекта.

— Насколько твои представления о работе в опенсорс совпали с реальностью?

— Со сроками в 4–5 дней (инструкцию нужно было написать очень быстро. — прим.ред.) ожидала, что сразу же, как только постучусь к программисту в личку, получу какие-то указания и буду работать. Ожидала, возможно, больше контроля с его стороны над своей работой и точно большего общения по моим вопросам!

В первый день договорились о том, что для меня подготовят базовый костяк с примерами — это случилось только к ночи, когда я была занята. Затем, с третьего на четвёртый день, я бешено вчитывалась, делала миллион заметок и вопросов в блокноте, прикидывала структуру доки — на тот момент очень сжатую, почти без заметных расширений в сравнении с костяком от программиста. Прямо в ней примечаниями с "❗" оставляла миллион вопросов, по которым вносила дополнения. Мерж случился утром шестого дня, а через несколько часов разработчик уже презентовал инструмент на конференции и, судя по всему, вместе с ним — меня. :-)

Сниженную частоту коммуникации понять можно, это сенсацией не оказалось — мы оба заняты фултайм основной работой. Из-за этого сейчас в доке есть некоторые слабые места — я рассчитываю их доработать на основании более вдумчивого общения с разработчиком после конференции. Возможно, расширю перечень освещаемых элементов продукта: добавлю порядок расширения функционала и программное устройство утилиты в целом.

— С какими трудностями столкнулась?

— Главной сложностью стала уже упомянутая разреженная коммуникация. Она наложилась на мою неуверенность в правильном понимании исходного кода на плохо знакомом языке. У работы в ночь были свои предсказуемые последствия. Но, к счастью, адреналин короткого срока и, возможно, кураж от настояще-всамделишного участия в техписательстве, их в достаточной степени купировали.

Интересно то, что ситуация попалась почти "лабораторного" характера: продукт небольшой и простой в функционале, и расписывать не надо было ничего, кроме порядка обращения на пользовательской стороне. Разработчик хорошо шёл на контакт. Он предоставил мне примеры кода и полную творческую свободу в описании всего, что нужно знать о них, вокруг них и между ними.

Я самостоятельно решала, какие моменты затронуть и в каком порядке, каким языком излагать, как что обозвать и какие средства оформления использовать. Это оказалась очень творческая работа, которая шла тем легче, чем дольше я знакомилась с продуктом.

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

Теперь моё имя запечатлено в истории этого проекта! Конечно же, это очень приятно, не говоря уже о приобретённом опыте общения с разработчиком и наличии готового документа.

— Какие рекомендации можешь дать техписам, которые тоже будут выполнять подобную работу?

— Ещё раз оговорюсь, что в конкретном моём сценарии как у меня, так и у разработчика присутствовал фактор подгорающего петуха. На носу была конференция, на которой разработчик в любом случае планировал выступать именно с рассказом об инструменте. Поэтому в результате мы были заинтересованы оба. Мне трудно представить, как организовать такой стимул при включении в отвлечённый проект, где никто никому ничего не обязан.

Я могу посоветовать разве что:

1) Иметь удобный канал связи с разработчиком.

2) Готовить вопросы пачками, желательно, пронумерованными, а не разрозненные озарения в течение дня. На нумерованные вопросы разработчику удобнее отвечать.

3) Если трудно сформулировать вопрос или сделать адекватное предположение для доработки — делать нарочно неадекватное и просить исправить. Модель раскачки обсуждения неадекватным предложением вообще очень эффективная.

4) Если разработчик избегает общения, попробовать изучить проект самостоятельно или спросить совета у знакомых программистов.

5) Помимо всего, что выше, самое существенное — беречь вашего разработчика. В добровольческой работе, каковой является опенсорс, поддерживать хорошие отношения первостепенно важно, ведь на них происходящее и держится. Здесь никто никому ни по ТК, ни по ГК ничего не обязан 😁. Так что только и остаётся, что действовать из позиций максимально возможных и уместных взаимопонимания, заботы и уважения!

— Спасибо, Полина! Профессиональных успехов тебе!

Автор утилиты mdis, разработчик Антон Жуков, признался, что коллаборация с техписом — настоящая находка для него.

— Полина — начинающая техписательница, которая захотела внести свой вклад в opensource. Мы в коллаборации написали отличную документацию, которая теперь лежит в репозитории. Мне наконец-то не стыдно показывать это широкой публике.

Полина Клименко и Антон Жуков специально для Техписалити!