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

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 уже переходят в чистовые стадии, скоро расскажем подробности
◦ на середину апреля договорились о записи подкаста 🌼

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

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

иииии мы в эфире, подключайтесь 🐈🐈

Статья на Boosty про ещё один способ борьбы за баланс в жизни 🌸