Работая в айтишечке
1.14K subscribers
287 photos
4 videos
56 links
Канал о том, как эффективно работать в IT: простые объяснения технических вещей, лайфхаки, лучшие практики и полезные инструменты для повседневных задач.

Автор: @Shevtsoff
Download Telegram
📝 The Good Docs Project

Сегодня расскажу о классном open-source проекте The Good Docs Project, который поможет создавать качественную документацию.

Это целая библиотека шаблонов и руководств по составлению документов для IT-проектов. Здесь есть всё: от описания процессов до детальных спецификаций.

Что внутри
— Готовые шаблоны документов
— Руководства по их заполнению
— Советы по написанию понятной документации
— Рекомендации по структурированию информации

🔗 Какие есть шаблоны
api-quickstart
— api-reference
— bug-report
changelog
code-of-conduct
— code-of-conduct-incident-record
code-of-conduct-remediation-record
— code-of-conduct-response-plan
— concept
contact-support
— contributing-guide
glossary
— how-to
— images
— installation-guide
— our-team
quickstart
— readme
— reference
— release-notes
— style-guide
— terminology-system
— troubleshooting
— tutorial
— user-personas

Перейти

💡 Подходит для
— Разработчиков
— Технических писателей
— Менеджеров проектов
— DevOps инженеров
— Всех, кто работает с IT-документацией

Спасибо создателям The Good Docs Project за то, что делают нашу работу удобнее!

Делитесь в комментах, помогает ли вам этот инструмент или знаете что-то похожее?

#documentation #tools #open_source
🔥52👏1
☕️ Фреймворк ШИП: как создавать материалы, которые действительно будут использоваться

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

Почему так происходит? Потому что одного компонента недостаточно.

За годы работы у меня сложился следующий фреймворк — ШИП (Шаблон, Инструкция, Пример). Это три компонента, которые работают только вместе.

📝 Шаблон: структура без путаницы
Шаблон — это каркас, который экономит время пользователя. Без него люди тратят часы на форматирование вместо сути.
Шаблон убирает когнитивную нагрузку. Пользователь фокусируется на содержании, а не на том, «как оформить правильно».

📖 Инструкция: путь к правильному заполнению
Шаблон без инструкции — как автомобиль без правил дорожного движения. Да, он выглядит красиво, но использовать его правильно не получится.

Что должно быть в инструкции:
— Для чего используется шаблон
— Как заполнять каждый раздел (не «что написать», а «как подумать»)
— Каких ошибок стоит избегать
— Кто отвечает за заполнение, если это совместный шаблон

Важно: инструкция должна быть короткой и по делу. Если она занимает больше двух экранов — пользователи её не прочтут.

👀 Пример: наглядная демонстрация идеала
Это самый недооценённый, но самый важный компонент. Люди мыслят через аналогии, а не через абстрактные правила.

Как создавать хорошие примеры:
— Показывайте реальные кейсы (с обезличенными данными)
— Выделяйте, что работает хорошо в примере
— Добавляйте комментарии: «В этом разделе мы описали конкретное действие, а не общую проблему»
— Для сложных шаблонов — сделайте 2-3 варианта: один идеальный, один с типичными ошибками и исправлениями

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

P.S. На самом деле на идею фреймворка ШИП меня натолкнули материалы проекта The Good Docs Project. Поработав с ними, сразу понимаешь как это классно.

#product #documentation #templates #userexperience #bestpractices
Please open Telegram to view this post
VIEW IN TELEGRAM
8🔥7👀3