Текущая фаза:
Программа «Сезон документации 2019» завершилась 6 марта 2020 г. См . график .
На этой странице содержатся рекомендации для технических писателей о том, как создать отчет о проекте после завершения работы над Сезоном документации в этом году.
Отправка отчета о вашем проекте
Когда начнется этап завершения проекта, вы сможете отправить отчет о проекте, заполнив форму, которая станет доступной в разделе «Завершение проекта» руководства технического писателя .
Информация для включения в отчет по проекту
В этом разделе описывается тип информации, которую вы можете предоставить в отчете по проекту. Форма отчета по проекту будет включать в себя поля для произвольного текста, а также вопросы с несколькими вариантами ответов.
Ссылка на вашу работу
Предоставьте ссылку, указывающую на описание проделанной вами работы.
Ссылка должна указывать на документ, содержащий краткое описание проделанной работы, документацию, которую проект с открытым исходным кодом объединил в свой репозиторий, краткое описание текущего состояния проекта, а также список проблем и уроков.
Ссылка появится в результатах сезона «Документация», опубликованных на сайте. Опубликованные результаты демонстрируют работу, которую вы выполнили во время программы. Опубликованные результаты также являются для вас отличным способом вернуться к своей работе как к части вашего резюме.
Вам следует поделиться ссылкой со своим наставником и попросить провести проверку перед отправкой отчета о проекте.
Требования к отчету по проекту
Примите во внимание следующие требования:
- Связанный контент должен позволять легко идентифицировать работу, которую вы выполнили во время «Сезона документации», то есть внесенные вами изменения или написанную вами новую документацию.
- Работа должна находиться в стабильном месте. Вы не можете изменить URL-адрес после отправки.
Кто-то другой должен иметь возможность использовать контент в целевой ссылке (или на нее ссылаться) для развития вашей работы.
- Если ваша работа выполнена на 100 %, другие люди смогут ею воспользоваться.
- Если ваша работа не завершена на 100%, должно быть ясно, что осталось сделать.
Хорошие примеры того, как описать свою работу
Вам не обязательно выполнять все (или какие-либо) из этих действий, но вот несколько способов удовлетворить требования:
Создайте запись в блоге, веб-страницу или общедоступную суть GitHub, в которой описывается проделанная вами работа, а также ссылки на сделанные вами коммиты и репозитории, над которыми вы работали. Если над проектом еще предстоит работа, включите описание этой работы. Вы также можете поделиться яркими или сложными моментами.
Это лучший вариант, поскольку он позволяет легко включить большой объем информации. Это хорошо, потому что ясно показывает проделанную вами работу и позволяет другим легко использовать и понимать ваш вклад.
Если вы используете GitHub и вся ваша работа покрывается одним запросом на включение, вы можете использовать эту ссылку.
- Убедитесь, что описание запроса на извлечение подробное.
- Убедитесь, что в описании четко указано, что работа предназначена для сезона «Документация».
- Если запрос на включение требует дополнительной работы после завершения сезона «Документация», убедитесь, что этот факт отмечен в последнем коммите сезона «Документация».
- Преимущество этого метода предоставления отчета по проекту заключается в том, что журнал изменений, список коммитов и комментарии к обзору собраны в одном месте.
Если ваш репозиторий GitHub предназначен только для Season of Docs, добавьте файл README, содержащий подробную информацию о вашей работе.
Создайте общедоступную папку на Google Диске и включите в нее все созданные вами исправления.
Создайте общедоступную таблицу с помощью Google Sheets и перечислите все свои коммиты.
Ссылка на одну проблему в общедоступном трекере проблем, содержащем четкие ссылки на вашу работу и все остальное, что уместно. Задача должна отслеживать всю проделанную вами работу. Убедитесь, что в задаче перечислены все коммиты или что коммиты можно легко найти другим способом.
Ссылка на унифицированную или контекстную разницу ваших изменений. Обязательно включите заголовок, в котором указано название вашего проекта по написанию технических статей и кто вы, чтобы это было полезно другим.
Плохие примеры описания вашей работы
Не делайте следующих вещей:
- Ссылка на tarball или zip-файл, содержащий исходный код всего проекта, или на ваш рабочий каталог.
- Ссылка на начало основного репозитория исходного кода проекта. Например, если вы работаете над cpython, эта ссылка бесполезна: https://github.com/python/cpython .
- Ссылка на ваш клон исходного репозитория проекта. Это затрудняет понимание ваших изменений, поскольку ваша работа смешана с работой других людей.
- Ссылка на описание вашего проекта на сайте Season of Docs.
Для наставников
Пожалуйста, помогите вашему техническому писателю создать правильный отчет по проекту. Важно сделать это, прежде чем создавать собственную оценку работы технического писателя.
Проверьте следующее:
- Подача должна соответствовать требованиям, описанным выше.
- Представление должно включать описание проделанной работы, удовлетворенных требований и причин принятия конкретных решений.
Идея Season of Docs не в том, что технические писатели штампуют массу документации. Важно, чтобы работа была потенциально полезна для хостингового проекта с открытым исходным кодом.