Комментарии 16
Работаю в крупной компании в роли технического консультанта. Не видел пока качественных тех.писов, не видел такой должности даже.
Эту роль свалили на тех.специалистов , они же и консультанты по продукты, они же и тестировщик релизов, они же и документы составляют. Криво-косо языком далеким от обычного пользователя видел написанные ТЗ, но как умеют так и пишут.
Так вы технический писатель (ТП) или админ БД? Вначал одно, в подписи иное.
Вы бесконечно банальны. Можно или аналитика дообучать писать. Или ТП дообучать разбираться в предметной области. Выбрали вы второе. И что? Вы старательно пытаетесь обосновать ваш выбор - но не убеждаете.
Есть один простой аргумент. Вы его, кстати, привели, когда говорили о >80 000 установок. Мол, нужна уже наконец качественная документация. А продукт у вас сложный. Насколько наскоро дообученный ТП сможет сделать исчерпывающую и точную документации ? Нмв, не сможет. Компетенций не хватит. Не формальных, а практических, на основе наработанных навыков. Ваши доки с вероятностью 100% будут содержать ошибки, которых аналитик бы не допустил.
Приличного ТП надо дообучать как аналитика, а не только как разраба или админа. Но значительно, нмв, правильнее получать от них точные данные. Видосики и интервью для этого и существуют. ТЗ, постановки аналитиков и пр. материалы.
ТП оформляет материалы, полученные от специалистов. С последующим согласованием (по моему опыту этого никогда не было, доки делаются в последний момент для закрытия контракта).
Достоинство вашего материала в том, что вы хотя бы тратите ресурсы на дообучение избранных жертв (неважно, разрабов или ТП). У меня был опыт, когда начальник провозгласил желание сделать из меня "гуру продукта", ходячий справочник. И даже пальцем не пошевелил 3 года.
*
Материал ваш не информативен. Это ваше субъективное описание вашего субъективного выбора, не более. По факту вы пошли по пути наименьшего сопротивления, не справившись с аналитиками и разрабами. Зарплата у них побольше, чем у ТП. И статус повыше.
если научить техписа админить БД, то он будет админить БД))
Как вариант, найти молодого не шибко опытного, но амбициозного админа и поручить ему разворачивать стенды.
От него будет много вопросов тем же разрабам, и на основании связки "вопрос/ответ" и можно будет писать неплохую документацию, вполне понятную не-админам.
На третьей инсталляции он перестанет задавать вопросы.
Даже администрирование ему не поможет, если решение проблем или особенности тюнинга не описаны в отдельных, легко находимых разделах документации.
В общем - на каждую левую резьбу нужно техническое описание.
Везде свои нюансы, конечно.
По себе скажу: переквалифицировался из сетевика в линуксоида (саппорт/внедрение микросервисного ПО). С разрабами/девопсами повезло - любой тикет детально описывается, на основании рабочего решения всегда пишется документация. Любое изменение продукта тоже описывается еще до релиза. Мне, как инженеру саппорта, платилась премия за наполнение базы знаний. Всё ок, все хорошо, все довольны.
Заскучал в саппорте и решил расти дальше, попал в джуны-девопсы. Компания та же, продукт и команда - другие.
По девопсной части - абсолютный ноль документации, у разработчиков документации тоже кот наплакал.
С ментором - тоже не всегда все хорошо; человек держит все в голове, вместо того, чтобы в ответ на мой вопрос "час копаюсь, не пойму почему не работает" направить в нужное русло - он чинил все сам и говорил что "я починил, все работает".
А т.к. проблем много, обратной связи мало, опыта и знаний у меня по девопсу тоже мало - лучшим решением было документирование проблемы и ее решения. Очень помогает запомнить всё.
А в начале месяца еще и ментор уволился и я теперь один джуню более 100 стендов разработчиков и весь Gitlab CI тоже на мне - поэтому объем документации по части девопс через месяц-два перерастёт суммарный объем документации программистов :)
Отталкиваясь от этого, и говорил - наймите неискушенного джуна, он вас завалит документацией. А более опытные коллеги причешут ее в полностью готовый вид
какие-то у вас не правильные инженеры) в универе как раз и учили проектировать, писать доки и реализовывать..
разворачивать дистрибутив, писать код это среднеспециальное..
Обычно проблема в другом (стоимости человеко часа). На написание документации нужно время. Стоимость часа опытного специалиста, с образованием, обычно выше часа опытного тех писа.
Но и тут не все так просто. Тех пис достаточно далёк от тех компетенций. А значит он может (да, в правильном формате) оформить ровно то что надиктуют тех специалисты. И тогда получается что час работы с докой стоит уже n часов тех писа + m часов диктов инженера. Так что иногда выгоднее иметь грамотного инженера, иногда тех писа.
Гораздо более интересная роль аналитика, системного и бизнес (это разные роли). Это технически компетентный специалист с компетенциями тех писа. Но и стоит он конечно дороже.
Не надо грузить аналитика так, что он на стенку лезет. И четко прописать в должностной инструкции, что участие в создании доков строго обязательно. Тогда он выкроит 5-20 минут на разговор с ТП по запись.
ни разу не встречал чтобы люди делали то что в должностной инструкции написано (ни шагу на лево или право)
на моем опыте должностная инструкция это очень обобщенное описание сути позиции и наверное надо больше HRу чем сотруднику
я конечно встречал дикие инструкции где программист и "несет материальную ответственность за сбой".. только почему при падении на 15 мин продукта у которого потери на,условно, миллион в минуту, еще никто на моей памяти не выплачивал (и не получал как запрос на выплату)
Можно пойти по другому пути - зафиксировать правила оформления документации и не принимать мержреквесты фичей без их описания. Осталось только описать и зафиксировать правила, ибо если что-то может быть понятно некорректно, оно будет понятно некорректно
Техпис - это аналитик, на которого не хватило в компании денег.
Подкину ещё один способ вырастить техписа в своём коллективе.
Представьте себе небольшую компанию, которая стоит перед тем же выбором, что и вы в самом начале. Допустим, решили новых сотрудников не нанимать, а выделить из команды человека, который уже знает продукт и хочет заниматься докой на фултайм. Это может быть сотрудник техподдержки, менеджер по работе с клиентами, юрист, либо стажёр, в общем, любой желающий.
Чтобы не тратить время и деньги, а делать доку сразу качественно, решили нанять сотруднику, который теперь техписатель, ментора. Вместе с ментором новый техписатель за 2 месяца прокачался так, как другие прокачиваются за 2 года. Не только переработал доку и написал новые разделы, но и написал гайд для всех, кто пишет тексты о продукте.
Профит!
Спасибо за статью, интересную тему подняли, подача хорошая. Решение доучивать DBA, желающих писать доку, отличное :)
Что триггернуло:
Писать ТЗ задним числом силами технического писателя — отвратительная практика, бррр. Плохо и то что задним числом, и то что это техписатель, а не аналитик.
«В своем классическом состоянии техпис — это вечный ждун материалов» — это не классическое состояние, это признак того, что в компании неправильно настроены процессы документирования и разработки.
«Техпису в IT можно не быть айтишником» — в смысле человек работает в айти-компании, пишет техническую документацию, разбирается в сложном продукте, но он не айтишник? Кря-кря-кря :)
Курица не птица, техпис не инженер