Код написан, а что с документацией? GitHub-сокровищница для тех, кто пишет

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

Речь о Awesome Technical Writing от разработчика Bolaji Ayodeji. И нет, это не очередной фреймворк или библиотека. Это то, что называют "awesome-list" — тщательно собранная и структурированная коллекция ссылок на лучшие ресурсы по техническому писательству. По сути, это карта сокровищ для любого, кто хочет научиться ясно и толково излагать свои мысли в тексте, будь то документация к API, статья в блог или просто описание pull request.

Давайте заглянем внутрь и посмотрим, какие сокровища там спрятаны.

Что внутри этой сокровищницы?

Репозиторий разбит на логичные разделы, так что найти нужное не составит труда. Вместо того чтобы часами гуглить "как написать хорошую доку", вы получаете готовую подборку проверенных материалов.

1. Учимся с нуля: Курсы и книги

Для тех, кто вообще не знает, с какой стороны подойти к написанию текстов, есть раздел с курсами. И что особенно приятно, начать можно бесплатно.

• Курсы от Google: Технические писатели из Google делятся своим опытом в серии бесплатных мини-курсов. Они охватывают основы, написание сообщений об ошибках и даже создание документации с учетом доступности для людей с ограниченными возможностями. Отличный старт, чтобы заложить правильный фундамент.
• Книги на все случаи жизни: В подборке есть как классика вроде "Technical Writing for Dummies", так и более современные книги, например, "Docs for Developers: An Engineer’s Field Guide to Technical Writing". Последняя написана инженерами для инженеров — минимум воды, максимум пользы.

2. Инструменты мастера: Чем писать и проверять?

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

• Для грамматики и стиля: Помимо очевидного Grammarly, здесь есть ссылка на Hemingway App. Этот сервис подсвечивает слишком длинные и сложные предложения, помогая сделать текст более читабельным. Есть и опенсорс-альтернатива — LanguageTool.
• Для совместной работы: Если вы пишете документацию командой, пригодятся ссылки на HackMD для совместного редактирования Markdown в реальном времени или старый добрый Google Docs.
• Для автоматизации: Интересная находка — Readme Markdown Generator. Это CLI-утилита, которая помогает быстро сгенерировать красивый и структурированный README.md для вашего проекта.

3. Следуем лучшим практикам: Стайл-гайды гигантов

Как правильно писать — e-mail, email или E-mail? Чтобы не изобретать велосипед и поддерживать консистентность в документации, существуют стайл-гайды (руководства по стилю). В репозитории собраны гайды от IT-гигантов:

• Google Developer Documentation Style Guide: Настоящая библия для тех, кто пишет для разработчиков.
• Microsoft Manual of Style: Еще один фундаментальный труд, который охватывает множество нюансов.
• IBM Editorial Style Guide: Классика, проверенная временем.

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

4. Вдохновение и сообщество

Техническое писательство — это не только про сухие инструкции. Это еще и про обмен опытом. В awesome-technical-writing есть ссылки на:

• Сообщества: Например, r/technicalwriting на Reddit или глобальное сообщество "Write the Docs", которое проводит митапы и конференции.
• Подкасты и видео: Можно послушать, как другие решают те же проблемы, что и вы.
• Блоги технических писателей: Список людей, на которых стоит подписаться, чтобы быть в курсе трендов и перенимать опыт.

Зачем это нужно лично вам?

Хорошо, список большой и полезный. Но как его применить на практике?

• Если вы начинающий разработчик: Начните с раздела "Courses". Пройдите бесплатный курс от Google. Научитесь писать понятные README для своих пет-проектов на GitHub. Это выделит вас на фоне других кандидатов.
• Если вы тимлид: Откройте раздел "Style Guides". Выберите один (например, от Google) и предложите команде его придерживаться. Это поможет унифицировать документацию во всех проектах и снизить порог входа для новичков.
• Если вы опытный разработчик и хотите делиться знаниями: Загляните в разделы "Useful Tools" и "Resources". Там вы найдете список платформ, которые платят за технические статьи, и инструменты для кросспостинга в разные блоги. Отличный способ монетизировать свой опыт.

Репозиторий awesome-technical-writing — это не просто список ссылок. Это отлично структурированный путеводитель, который поможет вам пройти путь от "не знаю, что писать" до создания документации, которой будут с удовольствием пользоваться ваши коллеги и пользователи.

В нашей профессии умение писать код — это лишь половина дела. Вторая половина — умение объяснить, как этот код работает. Этот репозиторий дает все необходимое, чтобы прокачать второй, не менее важный навык. Добавьте его в закладки — уверен, вы еще не раз к нему вернетесь.