Техниндзя | Дмитрий

Яндекс Диск не был бы Яндекс Диском, если бы не подкинул мне с утра подборку кадров двухлетней давности. Среди них я откопал этот кадр из серии «Дима до того, как стал знаменитым техписателем» 😄 Это было летом 2022 года, я присутствовал на защите дипломов выпускников ин.яза в Новосибирском педагогическом университете, задавал им вопросы про локализацию видеоигр, кушал пироги, таскал домой цветы на радость жене и строил планы того, как буду вострить лыжи для перехода в техническое писательство

Неделя Линукса прошла, но это вовсе не значит, что я вновь забью на ведение своего блога. Поэтому, сегодня я хотел бы поведать об одной интересной и немаловажной теме. Причем, настолько немаловажной, что на эту тему могут задать вопрос на собеседовании (плавали — знаем-с). Короче говоря, сегодня речь пойдет о том, как живет техническая документация (спойлер: она живет вечно, в сердцах и умах техписателей и стейкхолдеров) и какие циклы она проходит в течение своей «жизни» 🏃‍♂️ Вот основные «жизненные вехи» тех. документации: 1️⃣Постановка задачи Театр начинается с вешалки, а документация — с определения своих целей и задач. На первом этапе важно понять, для кого будет предназначена документация, какие проблемы она будет решать и какие требования к ней предъявляются. Иначе говоря, эдакий бермудский золотой треугольник «аудитория - цели - требования». 2️⃣Извлечение информации На этом этапе мы получаем всю информацию, которая будет в дальнейшем задокументирована. «Извлечь» нужную информацию можно несколькими способами: - изучить уже существующие материалы по разрабатываемому продукту; - самостоятельно «потыкать» продукт, если возможно; - позадавать вопросы «хранителям знаний». Небольшая ремарочка: я как-то весной переводил статью про то, как задавать вопросы и извлекать техническую информацию — она по ссылке. 3️⃣Написание Вся необходимая информация извлечена, согласования получены, а дальше-то что? Правильно, настала пора писать первоначальный вариант документации. Но не просто его написать, а сделать его логичным, понятным, точным и полным (а теперь — бермудский прямоугольник). 4️⃣Проверка Первоначальный вариант документации готов, но это еще далеко не все. Теперь документация должна пройти очень много кругов ада этапов проверки на всяческие орфографические, стилистические, синтаксические и прочие ошибки выжившего. Конечно же, не стоит забывать и про соответствие стайлгайду, требованиям заказчика, корректность и полноту изложенной технической информации. 5️⃣Утверждение После прохождения всех кругов ада под названием «проверка» наступает момент, когда заказчик вместо привычного «Давай по-новой, Дима, все фигня» говорит «Все замечательно, документация соответствует всем требованиям». Это значит, что теперь документацию можно отдавать пользователям на растерзание. 6️⃣Публикация На этом этапе документация становится доступной для пользователей Причем, везде она распространяется по-разному: кто-то публикует ее на отдельном сайте, а кому-то предпочтительнее сконвертировать ее в PDF. Кстати, а как вы распространяете свою документацию среди читателей? Пишите в комментариях, если позволяет NDA 🪼🪼🪼 7️⃣Поддержка Документация написана, проверена, утверждена, опубликована — все классно и прекрасно. Но и здесь наши техписательские полномочия — не все. Необходимо же еще поддерживать ее актуальность (например, если в продукт внедрили новый баг новую фичу или убрали неактуальную) и работать с фидбеком от пользователей. Иногда даже приходится исправлять свои же ошибки… 🫤 Подводя итоги, можно сказать, что ЖЦТД — это многогранный, многоэтапный процесс, и кропотливая работа на каждом из этапов ЖЦТД станет залогом высокого качества технической документации 😎

На злобу дня, так сказать 😁

Финальная партия вопросов – в студию)