Один из важнейших навыков для техписа — разбираться в больших объёмах новой информации и структурировать её для читателя 🐸


Как это сделать:

1. Определить цель — если понять зачем, весь процесс становится прозрачнее и легче.

2. Организовать логику — все разделы, абзацы и предложения должны наслаиваться друг на друга и организовывать единую последовательную цепочку информации.

3. Использовать форматирование — заголовки, плашки, списки, таблицы — ваши верные спутники в мире текстов, особенно технических.

4. Выделить важное — но только действительно важное, иначе можно выделить всю документацию и надо будет выделять из выделения.

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


Помните, что структурированная и чёткая подача информации значительно упрощает восприятие и относится не только к конкретной статье, но и ко всему представлению бренда 🐸

#techdoc

У кого уже дёргается глаз от словосочетания «Эффективные коммуникации» — ставьте 😨

Из необходимости собирать много информации и укладывать её особенными образами, вытекает навык общения со смежниками, командой и заказчиками. И с каждым из них надо говорить понятными им терминами, поэтому жаргонизмы и сокращения надо либо объяснять, либо избегать. Есть у меня история, когда из-за одного слова пришлось разворачивать месяц работы 🫠

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

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

И на десерт — сообщайте всем сторонам о статусах. Лучше всего это делать в самой задаче комментарием. Поставьте себе напоминание раз в неделю и ходите отписывайтесь в задачах, что сделали, какие были сложности, что будете делать. Даже если ничего не сделали — так и напишите. Иначе вас придут долбить в личку, вы будете стрессовать и результат будет «на отвали» 🫣 Не успели? Проанализируйте и честно напишите в статусах «не успел».


Примите, пожалуйста, что вы — специалист. И вокруг вас тоже специалисты. И вы не друг с другом боретесь, а наоборот — вместе строите что-то ценное и полезное 🤩

#mngr

Сегодня коротко ловушках, которые ждут нас в техническом документировании.

1. Запутанный язык. Сложно не значит круто. Простота и ясность — наши лучшие друзья.

2. Несоответствие стиля. Если документ выглядит как пазл из разных кусочков, это плохо. Единый стиль — залог понятности.

3. Непроверенные факты. Ошибки в данных могут стоить дорого (буквально, спросите у юристов). Проверяйте, проверяйте и ещё раз проверяйте!

4. Игнорирование фидбека. Мы не всегда идеальны и это нормально. Слушайте коллег и пользователей.


Коротко: держите тексты простыми, стиль — единым, факты — проверенными и уши — открытыми для советов 👋

#techdoc

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


Но как сделать это эффективно? Есть три базовых варианта:

⏳ Создайте план или график регулярных обновлений. Это поможет не забыть про необходимость пересмотра документов.

💌 Следите за изменениями в продукте или услуге, о которых вы пишете. Подпишитесь на рассылки, договоритесь о регулярных встречах, ходите на синки.

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


Высший пилотаж — автоматизация актуализации. Но тут уже сильно завязано на конкретно ваши инструменты и процессы 🐌

#techdoc

Помните, мы нанимали в декабре?

У нас есть ещё одна бонусная вакансия 😍

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

На хх выкладывать не будем, пройдёмся по уже накопленной базе кандидатов. Поэтому если вы не откликались раньше — присылайте свои резюме мне в личку @ushkatia 😼

UPD
Пока всё, отсматриваем резюме, спасибо за отклики.
Если вы откликнулись, но вам не напишут до 5 февраля, вы всё равно останетесь в нашей базе кандидатов и в следующую вакансию мы снова на вас обратим внимание.

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

Agile-дока 🍊

Agile — это не просто способ разработки ПО, это философия, подчеркивающая быстроту, гибкость и адаптивность. А как же быть с документацией, которая требует точности и внимания к деталям? Ключевое слово здесь — «синхронизация».

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

И нельзя забывать о коммуникации. В Agile коммуникации — часть документации. Регулярные встречи, совместная работа и обратная связь помогают держать документацию up-to-date 🚲

#mngr

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

Поэтому в такой доке должны быть такие вещи:

⭐️ описание функций и методов;
⭐️ примеры кода для быстрого старта;
⭐️ инструкции по интеграции.

Всё должно быть написано просто и понятно. Чем легче разработчику понять ваш API, тем быстрее он сможет его использовать. Да и в принципе документация — единственное окно входа в API, поэтому без неё не получится.

Из-за этого иногда кажется, что документация API — это что-то запредельно сложное и писать её могут только старшие специалисты. Категорически не соглашусь ☠️

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

#techdoc

Давайте про виды картиночек в доке?


📌 Диаграммы, гистограммы и прочие графики. Используйте гистограммы и круговые диаграммы, чтобы наглядно демонстрировать статистические данные. Это помогает быстро оценить объемы, соотношения и тенденции.

📌 Шаги процесса через инфографику. Сложные процессы легче понять, когда они визуализированы шаг за шагом. Инфографика с иконками и краткими описаниями делает инструкции более доступными.

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

📌 Деревья и флоу-чарты. Идеальны для изображения архитектуры системы или потока данных. Они помогают визуализировать структуру и взаимосвязи компонентов.


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

Хотяяяя всё зависит от вашей ЦА ❤️

#techdoc

🌟 Лингвошутка 🌟

Занимаюсь китайским
Надо было перевести предложение
«После долгого рабочего дня у меня часто болит голова»

Выбрала не тот иероглиф
Получилось примерное такое:
«После долгого рабочего дня моя голова плещется ручейком»

В принципе, смысл не пострадал.

🐈 Новости 🐈

В этом году лидовья часть Ozon-техписов читает курс в Иннополисе 😮

На первой неделе разобрались в основах, обсудили инструменты 🐈

А остальной командой начинаем готовиться к сезону конференций — анонс первой уже совсем скоро 💻

#lifestyle

В Иннополисе из-под снега робко виднеется асфальт, и разные комьюнити тоже выходят из спячки 🌸

◦ 6 марта — увидимся на митапе Kaspersky Tech Fest
◦ 12-13 апреля — готовлюсь выступать на Стачке в Ульяновске
◦ прогоны к Techdoc Meetup 4 уже переходят в чистовые стадии, скоро расскажем подробности
◦ на середину апреля договорились о записи подкаста 🌼

Ещё об одной штуке обговариваем детали и, надеюсь, скоро анонсируем 🦋

А в Инно завтра начинаем второй блок лекций — о типах целевых аудиторий, основных документах для них, метриках и исследованиях 🧁