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

Очень спорное утверждение, мягко говоря. Вы путаете тёплое с мягким. Понимание иметь и представление, возможно, и хорошо, но умышленно и целенаправленно лезть в маркетинг и писать подобные текстовки будучи Техническим (!), в первую очередь, Писателем, несколько неоднозначно, как минимум.

Кому важно?

За «маркетолога» доплачивать будут? Если будут, то сколько? Что наш любимый рыночек на это отвечает?

Делать работу за двоих, а то и троих специалистов, а получать как за одного… Я даже комментировать это не стану.

Для маркетинговых текстов есть специально обученные люди — маркетологи, сео-копирайтеры, продажники. Зачем забирать у парней их хлеб не очень понятно.

Это концепция JTBD и она используется тоже не только в маркетинге.

Ну вопрос вопросом. Кто хотел не спрашивал и не писал, он взял и сделал. И заслужил уважение.

Откуда вопрос? Оттуда, что люди смотрят на рынок, смотрят на количество предложений топовым специалистам из других направлений (тот же фронт, бэк, SRE), смотрят насколько это ценится и сколько парням готовы платить. Чем больше предложений, чем больше платят, чем больше идут на их условия, тем большей ценностью/почётом парни обладают/пользуются, в том числе и в глазах своих коллег и окружающих. То есть людей ценят. И выражается это в первую очередь в материальных благах.
А теперь сравните это с предложениями и зп Технических Писателей (с поправкой на рынки, конечно, ну и культуру в отдельных странах) и всё сразу встанет на свои места.
Относиться к подобному можно как угодно. Факт остаётся фактом.
Рынок сегодня решает всё.

Открываем HH, смотрим зарплаты техписов. Открываем oracle.ru, смотрим сколько получают сеньоры разрабы (воротят нос от 300к)
Делаем выводы )

это очень древний фундаментальный труд. Рекомендую ознакомиться с диалектикой Энгельса — это поднимет вас выше ещё на две головы. Каждый техписатель должен владеть диалектикой.

ЗАЧЕМ???

довольно распоостранённое заблуждение, когда пытаются скрестить технические и продающие тексты. А что касается программных продуктов, то это вообще задача аналитиков из команды продакт-менеджмента. Они не маркетологи в классическом понимании.

Какую дырку хочет просверлить владелец Ламборгини. Чем его дырка отличается от дырок владельцев Роллс Ройса и Тойоты?

Дырка в ламбе стоит дорого!

Суббота же, ребята

Чтобы продать такую дырку без навыков маркетолога не обойтись!

Абсолютно согласна с @EveryOneDiesInUtah . Если технический писатель выполняет работу маркетолога и продуктовнера, то зачем они нужны вообще? Проводить маркетинговые исследования - отдельная сложная задача (если всё делать правильно), которая занимает много сил и времени. Ещё и требует постоянно креативного подхода, что техническим специалистам совсем не свойственно. Если каждый будет делать свою работу, то результат будет супер. Если техписатель будет делать за всех работу, то результат будет скорей меньше в бизнес и больше в техническое описание, ну и о продукте будет знать только техписатель.

Описывать технические характеристики дырок неверно, нужно описывать задачи дыркосверления.

Как показывает практика, техпис может делать работу и тестера и аналитика и всех кого только можно. )

Как неверно? Обязательно надо описать ТТХ дырки! А если дырок несколько? Как понять, какая именно нужна?

Тут скорее дело в том, о чём написал Семён немного выше — техписовская работа воспринимается как более простая и потому второсортная. Возможно, это из-за того, что формальный порог входа ниже. Или речь не о техписе, а о девопсе-джуне, который вынужден временно работать техписом.

Ясно, что SRE в среднем платят больше, чем техписам) Другое дело, что редкий SRE сможет получать удовольствие от написания документации, и редкий техпис будет с интересом возиться с кубернетесами. А если работа не приносит ни грамма удовольствия и не подходит, то что толку от х1.5-х2 зарплаты, если N часов в день придётся заниматься чем-то утомляющим и «не своим», а потом неизбежно выгореть?

Просто личное мнение) Условно говоря, условная я могла бы пойти работать фронтом и достаточно быстро выйти на х1.5 от нынешнего дохода техписом-техпереводчиком. Правда, неизбежно взвыла бы через пару месяцев от необходимости приближаться к условному реакту ближе, чем на километр. Не то, да и всё, невозможно же вечно работать на раздражающей работе.

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

По моим условиям такая инструкция подойдёт ровно половине моих пользователей: тем, которые знают задачу. Есть другая половина, которые уже успешно выполняют какую-то смежную задачу, обнаруживают новую для себя опцию и НЕ ЗНАЮТ для какой задачи она нужна. Даже если вы эту опцию опишите в рамках другой процедуры, такие пользователи ее не найдут, потому что не знают задачу, а ведь возможно им она очень пригодится. Тут поможет только такой формат, который вы предлагаете отвергнуть: справочное перечисление всех опций с пояснением, зачем они нужны.

Верх неприличия считать, что документация согласно ГОСТ в word_е будет оплачиваться также, как и способность развернуть кубик.

Зато очень прилично будет считаться если техпис глядя в условный main.js сможет прочитать этот файл, поймёт что делают функции и напишет комментарии для функций, которые потом через jsdoc, например, выложит в виде сайта.