Что нужно знать, чтобы стать хорошим техническим писателем?

Чтобы стать хорошим техническим писателем, нужно иметь определенный набор навыков.

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

🐈 Второй навык, который вам нужен, — это умение писать понятную и структурированную документацию. Необходимо строить текст, чтобы он был понятен и удобен для чтения.

😮 Важно помнить, что для продвижения продукта/выполнения проекта необходимо переводить технический язык на язык понятный всем. Для этого можно использовать базовые знания по маркетингу и продажам. Умение заинтересовывать читателя, но при этом честно и правильно описывать продукт или проект — это непременный навык технического писателя.

🐈 Еще один навык, на который нужно обратить внимание, — это внимательность к деталям и умение работать с непонятным материалом. Часто приходится сталкиваться с материалом, который трудно понимать, и здесь вам нужно уметь сфокусироваться на основном и разобраться в деталях.

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

#sponsored_by_AI

Две мысли

1. Когда хочется быть «хорошим» подумайте, пожалуйста, что такое этот «хороший» и кто вам его навязал.
2. Армин 😅

Статья на vc.ru о том, почему не надо быть «хорошим»

#monday_link

Medium опять заблокировали

Сколько не пыталась на что-то другое перейти ради лонгридов — он всё же оставался самым привычным и приятным. Иех.


Всё равно планировала делиться статьёй с Хабра 🐈

D&D как инструмент тимлида: решаем проблемы команды с помощью разговорных ролевых игр

Всегда очень скептически отношусь к таким методам, потому что часто найдётся один ворчун и всё испортит и часто этот ворчун — я 🐈

#monday_link

Напоминаю, что у нас сегодня митап 😎

запись будет доступна по ссылке, которую вам пришлют после регистрации на мероприятие, поэтому жамк 😭

Стайлгайд и как его делать

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

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

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

Как составить стайлгайд

🐻 Определите свою целевую аудиторию и то, что она хочет получать от вашей компании в текстах.

⭐️ Определите ваш бренд и то, что вы хотите передать через него.

👩‍🎨 Составьте документ с описанием всех правил оформления текстов, шрифтов, цветов, логотипов и других элементов дизайна.

🔄 Удостоверьтесь, что документ выполняется вашей командой и ваши действительно подходят на случай изменений в будущем.

#sponsored_by_AI

Подборка лучших книг по техписательству на 2023 год

Но все на английском и ни одной по ГОСТам)
Многие проповедуют продуктовый подход к доке, часть именно о языке [английском], поэтому не всё актуально для наших реалий, но всё равно стоит ознакомиться, если вы пишете документацию 🧑‍🎓

*все очень базовые, поэтому особенно рекомендую, если только вкатываетесь в техписательство

#monday_link

С международным днём йоги 😑

Если вам нужен был повод, чтобы сделать сегодня зарядку — вот он 🐈

Если вы уже потренили — держите лапу кота и продолжайте в том же духе 🐾

5 шагов для публикации доки

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

Шаг 1: Спланируйте свою документацию

Перед тем, как начать писать, ответьте на вопросы:
• кто ваш читатель?
• что вы хотите до него донести?
Помните, что не у всех пользователей одинаковый уровень знаний — не следует предполагать, что читатель всегда знает, о чём вы говорите.

Шаг 2: Структурируйте свой материал

Когда уже понятно что и для кого — надо решить «как». Определите, как будете группировать информацию по разделам и в принципе какой формат документации подходит для вашего случая. Вы можете разбить доку на главы, подразделы; добавь списки, таблицы или диаграммы, чтобы помочь понять информацию.

Шаг 3: Напишите текст

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

Шаг 4: Просмотрите и исправьте ошибки

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

Шаг 5: Опубликуйте документацию

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

🐈🐈🐈
#sponsored_by_AI

«Правильные JIRA issues». Как правильно разбивать задачи на тикеты

Статья на habr о личном опыте автора с тикетами в Jira

И напомню, что любой чужой опыт надо сначала взвесить, а потом бежать внедрять у себя только те части, которые вам помогут и только в той адаптации, которая подходит вашему случаю ❤️

#monday_link

Что такое #sponsored_by_AI ?

Вообще это немного трёхэтажный процесс постинга всяких текстов 😥

Если очень в общих чертах — это тексты, которые пишет ChatGPT по моему очень замороченному промту. Промт зашит в бота, поэтому я просто шлю ему тему или тезисы и он докручивает это до поста. А потом я докручиваю до читаемого текста.

Не всегда до «хорошего текста», стараюсь убить в себе перфекциониста из-за которого в принципе ничего не пишется 😐

Вот и получается, что AI как бы даёт основу текста => спонсирует мои полезные лонгриды 🐱

«Давай скрины добавим, ещё и стрелочками-циферками украсим всякими, чтобы пользователю понятнее было. О, и напишем инструкцию сразу на скрине»

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

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

А если вы переводите доку на несколько языков — умножайте стоимость одного скрина на количество локалей. И ещё на полтора.

Вместо скриншотов лучше рисовать схемы или делать гифки. Но тоже только для своих сервисов!

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

Если вы все же решили использовать скриншоты

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

Внимательно оцените все риски и преимущества использования скриншотов. Помните, что ваша главная цель — помочь пользователям, а не запутать их еще больше 😤

#sponsored_by_AI