Обзор на книгу Docs for Developers: An Engineer’s Field Guide to Technical Writing, которая вышла в сентябре 2021. В посте есть спойлеры, если хотите сохранить интригу не читайте этот пост.
Книга написана в соавторстве техническими писателями из Google, Microsoft, Stripe и Monzo.
Авторы говорят, что:
Книга разработана как ресурс, который нужно держать под рукой, чтобы вы могли включить написание документацию в процесс разработки. Эта книга поможет вам создать документацию с нуля. ©Еще обсуждение книги с авторами можно послушать в подкасте Write the Docs.
Что зашло
- Легко и быстро читается.
- Книга построена как хорошая документация, не обязательно читать ее всю, если есть пробелы в какой-то конкретной теме, например, вы не знаете как оценить качество документации, то можно прочитать только одну главу. Хотя авторы рекомендуют читать книгу по порядку 😉
- Из книги можно собрать коллекцию цитат про важность документации и правильные подходы. Тезисы подтверждены ссылками на научные статьи. Я нашла статьи, которые раньше не читала.
- Есть список необходимых инструментов, чтобы написать и опубликовать первую документацию (Hugo, Vale, Netlify).
Не зашло
- Я не люблю рассказы внутри обучающих книг, а тут был рассказ про стартап, который не документировал свой API, а потом им нужно было обучить первого клиента и они ой как пожалели. Пример мне показался слишком далеким от реальности. Я эти части пропускала, чем закончилась история не знаю.
- Я ожидала прочитать реальные истории из опыта авторов, про подходы к документации в их компаниях и много практики. Этого в книге нет.
Однако
Книга мне понравилась. Но перечитывать и держать ее под рукой я не буду.
Книга подойдет всем начинающим техническим писателям. Потому что в ней не только про документацию для разработчиков. В книге есть много базовых вещей: что нужно определить аудиторию вашей документации и писать для нее; что документацию сканируют, а не читают; что писать нужно коротко, текст делить на блоки. Эти принципы правдивы для любой документации.
Если вы технический писатель с опытом, то бросать все и начинать читать книгу не надо.
Я не верю, что много разработчиков или менеджеров прочитает ее, особенно кто-то из стартапа, ведь это 200 страниц.
#developerexperience
