Менторю технических писателей и их работодателей
Как на самом деле нужно понимать ГОСТ. Это не закон, которого нужно строго придерживаться. Это вообще не закон. Это правила, которые соблюдают некоторые игроки индустрии, договорившиеся между собой.
Но лучше бы они хотя бы попытались скосплеить кодекс Хабра: https://habr.com/ru/docs/authors/codex/
Что делать с ощущением «все вокруг знают и умеют гораздо больше меня», которое неизбежно возникает у любого, кто посидел в профчате хотя бы недельку?
Во-первых, осознайте, что это иллюзия. Да, все вместе они знают больше. Но вы незаметно слепили супермена у себя в голове — в реальности это не один человек, а целая команда.
Во-вторых, сразу, как только заметите мысль про «всех вокруг», открывайте блокнот и записывайте конкурентные преимущества, которые у вас точно есть. Например:
— «Все» уже трудоустроены, а вы — нет, вас можно нанять.
— «Все» живут в дорогом регионе и обходятся работодателю дороже, а вы нет, вы можете получить тот же уровень жизни за меньшие деньги.
— «Все» уже давно не испытывают энтузиазма, а вы — да!
— «Все» — зумеры, вы — миллениал, а у работодателя половина команды состоит из бумеров (ладно, это я нафантазировала ради гротеска).
Список можно продолжать. Главное — начать его составлять. После того как вы немного успокоитесь, можно будет найти сильные стороны, которые имеет смысл прокачивать лично вам.
Думаю, технический писатель по характеру — ремесленник. В том смысле, что любит продукт делать сам, своими руками. А документация всегда продукт осязаемый, постоянно радующий нас, ремесленников, конкретными результатами. Сели, написали один абзац — и уже стало хорошо! Не надо ждать два года до MVP.
Если вам стало интересно, какие у ремесленников харды и софты. Читайте дальше!
На мой взгляд, у джуна и мидла харды такие:
Умение хорошо писать инструкции, любые.
Умение пользоваться тем, о чём пишешь.
Умение пользоваться инструментами, в которых тебе приходится писать.
У синьоров харды немножечко другие. Очень зависит от компании. Тут может быть управление процессом и командой, и стайлгайды, и докопсинг, и метрики с бюджетами. А может быть синьор просто умный и очень круто разбирается в IP-сетях.
Но вернёмся к джунам с мидлами. Умение общаться я отношу к софтам. Желание самостоятельно разбираться в сложной области гораздо важнее умения общаться. Если вы, такой общительный, постоянно будете дёргать всех, чтобы вам объяснили-показали, и при этом полученное знание не будет оседать в вас и приумножаться в доке. Вы просто разочаруете команду. И в конце концов вас сошлют в (бухгалтерию) менеджеры.
Простой, быстрый и бесплатный тест на профориентацию.
Кто вызывает у вас зависть? Почему? Что он—она делает? Что именно вас впечатляет в результатах?
Что это за роль в экономике: сотрудник в найме, учёный на грантах, волонтёр или вообще целый бизнес?
Когда вы почувствовали укол зависти, в каком контексте находился ваш предмет зависти? Выступал на конференции или что-то ещё? Сколько процентов от общего времени занимает эта активность, как думаете?
Если выяснится, что для результата, который вызвал у вас зависть, нужно много работать и 80% времени делать рутинные, неинтересные вещи, ваша зависть уменьшится или не сильно?
Если хотите читать вопросы, которые я задаю на менторских сессиях, маякните как-нибудь, буду выкладывать на Хабр дальше.
Инфостиль разрешает вам писать просто и ясно. И не поощряет вас делать вид, что вы умнее, чем вы есть на самом деле.
Всё. Больше инфостиль ни в чём не виноват. Все проблемы, все неудачи — из-за вас, а не из-за инфостиля.
Стиль — это стиль. Если воспринимать моду на термины и графические знаки именно как моду, предмет перестаёт быть таким уж холиварным. Не нужно спорить. Нужно просто всё время спрашивать себя, на кого я хочу быть похож. На свою жилконтору или на DigitalOcean. Главное не оказаться охранником из книги Пелевина:
— Принято так, — сказал охранник, снимая со стены один из фонарей и протягивая его Сердюку. — Вы ведь галстук тоже не от холода носите.
Вот примеры сложных выборов :)
Вначале было слово e‑mail, потом вариант email (без дефиса) был принят в словари страны происхождения и попал во все англоязычные гайды. То есть был принят большинством. Сейчас дело не в том, нравится вам лично этот вариант или не нравится, а в том, какую одежду вы хотите носить — ту, что была модной десять лет назад, или ту, которую сейчас носит ваша любимая компания.
Ещё пример, тоже про большинство. «Кавычки‑ёлочки». Хорошо сочетаются с кириллическим алфавитом. Носят примерно с 15 века. Но в 21 веке всем внезапно стало лень и теперь я очень часто вижу программистские кавычки в текстах, а не в коде. Мне ёлочки нравятся. Жаль, если их таки вытеснят программистские кавычки. Потому что особого практического смысла это иметь не будет. А красоту мы потеряем.
Этот пост написан специально для одного человека, который спросил, в чате техписателей, как ему, техписателю, «прокачать структуру [технической документации] и силу слова».
Я была бы не я, если бы у меня не нашлось короткого и универсального совета, который подойдет любому человеку, пишущему любой текст, похожий на инструкцию. Ведь техническая документация — суть инструкция.
Универсальный совет
В процессе работы над любым текстом, похожим на инструкцию, регулярно спрашивайте себя:
1. Какую задачу сейчас решает читатель?
2. Какая информация у читателя уже есть?
3. Какой информации читателю не хватает, чтобы решить задачу?
Этот набор вопросов для самопроверки поможет написать техническую статью, выбрать структуру документации, и даже сформулировать вопрос к чату.
Уже лет 10 про роль техписателей активно рассказывают сами техписатели. Однако за последнюю пару месяцев я лично несколько раз слышала вариации на тему: «у нас ТЗ пишут аналитики, значит и на пользовательскую доку аналитика наймём» или «ищем техписателя, который будет писать нам ТЗ». Но добило меня: «я думал, что аналитик — это следующая стадия развития техписателя».
Технический писатель — это тот, кто пишет техническую документацию?
И да и нет. Техническая документация — это не только техническое задание или руководство пользователя. Ошибка — думать, что техническую документацию пишет какой‑то один специалист. Документация нужна на разных этапах разработки продукта, значит и пишут её разные специалисты.
Технический писатель — это тот, кто пишет технические задания?
Нет. Технический писатель создает инструкции к сложным объектам.
Вспомните, какие инструкции лежат у вас дома. Вот их техписатели и написали. Техписатели не спрашивают покупателей — какой шкаф вы бы хотели. Зато рассказывают, как его собрать из того, что есть в коробке.
Я в чём‑то сложном разобралась, научилась этой штукой пользоваться, и объяснила другому так, чтобы он сказал — спасибо, я всё понял. Если штуки ещё не существует, но мне уже надо написать, как с ней работать, то я не техписатель, а, например, менеджер продукта;)
Так, а что техписатель делает на работе?
На работе техписатель разбирается в предметной области, а затем искусно формулирует инструкции для пользователей.