Подготовка технической документации *

Пошаговые инструкции сборки — больше не ад для техписов

Изначально система автоматической генерации документов требует значительных затрат. Если конфигураций оборудования всего несколько, то раздельные инструкции проще и быстрее написать вручную, чем создавать под них систему.

В нашем случае разработка самой системы динамической документации и подготовка контента для первых четырех продуктов в ней заняли в сумме около 1300 человеко-часов. Этот самый тяжелый и затратный этап включал изменение логики, наполнение и отладку системы и согласование изменений с технологами. 

На данный момент мы собрали из исходников документы для 647 конфигураций серверов. Даже при таком сравнительно небольшом количестве инструкций мы простым делением получаем затраты на один документ в размере 2 человеко-часов. Это в 12,5 раз дешевле, чем писать отдельные инструкции вручную — выше мы оценивали затраты такого подхода. В итоге с документацией справляются шесть человек — а если бы мы делали инструкции вручную, потребовалось бы не меньше 13 сотрудников. После внедрения конструктора мы оценили дальнейшие трудозатраты, продолжили работу с динамической документацией, и уже через несколько месяцев система начала окупаться.

Глеб Свистунов, руководитель отдела производственной документации YADRO, в своей статье рассказал о подходе динамической документации. С ним составлять пошаговые инструкции сборки оборудования для огромного количества конфигураций гораздо эффективней, чем вручную.

Как навели порядок в работе техписателей и ускорили процессы

Когда у команды технических писателей на одном только портале свыше 1200 документов, управление информацией требует четкой структуры и выверенных процессов. Специалисты постоянно сталкивались с десятками исходников и тратили много времени на поиск нужной информации. Это замедляло выполнение задач и мешало команде действовать слаженно.

Чтобы навести порядок, команда предприняла несколько шагов:

• Ввели единый стиль оформления задач, документов и исходников.

• Определили правила именования файлов, веток и структуру репозитория.

• Согласовали формат взаимодействия внутри команды.

• Разработали и зафиксировали внутренний стайлгайд — живой документ, который мы регулярно улучшаем, если это помогает сократить потери.

Стали шире использовать возможности разметки: избавились от лишнего, ввели переиспользование через ключи (conkeyref, keyref) и упростили поддержку кода. Поработали и с визуальной частью:

• Ввели правила для изображений: фиксированные размеры, формат, плотность.

• Стандартизировали визуальный стиль.

• Убрали визуальный шум, сфокусировались на главном.

• Установили лимит на размер изображений для ускорения загрузки.

Так, мы улучшили восприятие документации, снизили нагрузку на портал и ускорили производственные процессы. Визуальный порядок стал частью культуры качества.

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

Подробнее о бережливом подходе к технической документации читайте в статье Ивана Холодкова, старшего технического писателя направления производственной документации в YADRO.

Саботируйте процесс накопления знаний и документирования, чтобы вас ни в коем случае не могли уволить!

Ну ладно, это кликбейт 😅

В подкасте «Техкомпод» поболтали с Вовой о процессах, менеджменте знаний, структурировании документации и Gramax. Предлагаем вам тоже послушать и присоединиться к обсуждению!

• Расшифровка выпуска

• Яндекс Музыка

• Apple Podcasts

Новая версия Gramax!

• Сравнение ревизий. Можно сравнить текущую версию каталога с одной из предыдущих.

• Экспорт в корпоративных шаблонах DOCX. Добавили возможность загрузить корпоративный шаблон DOCX и экспортировать статьи и каталоги в этом шаблоне.

• Избранное. Каталоги и статьи можно пометить как Избранные для быстрой навигации. Это доступно как в приложении, так и на портале документации.

• Связанные статьи. В меню статьи можно просмотреть: куда ссылается статья и какие статьи ссылаются на нее.

Об этих и других изменениях читайте в Release Notes 🔥

Думаю, технический писатель по характеру — ремесленник. В том смысле, что любит продукт делать сам, своими руками. А документация всегда продукт осязаемый, постоянно радующий нас, ремесленников, конкретными результатами. Сели, написали один абзац — и уже стало хорошо! Не надо ждать два года до MVP.

Если вам стало интересно, какие у ремесленников харды и софты. Читайте дальше!

На мой взгляд, у джуна и мидла харды такие:

1. Умение хорошо писать инструкции, любые.

2. Умение пользоваться тем, о чём пишешь.

3. Умение пользоваться инструментами, в которых тебе приходится писать.

У синьоров харды немножечко другие. Очень зависит от компании. Тут может быть управление процессом и командой, и стайлгайды, и докопсинг, и метрики с бюджетами. А может быть синьор просто умный и очень круто разбирается в IP-сетях.

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

Как подход Docs-as-a-code применили в создании документации для TestY TMS

Команда разработки системы управления тестами TestY объединилась с командой технических писателей, чтобы создать удобную документацию.

Для ведения документации выбрали подход Docs-as-a-code. Документация хранится вместе с кодом приложения. Для написания и сборки использовали более-менее классическое сочетание: rST-формат в связке со Sphinx. 

Инженеры уверены, что такой вариант предоставляет большую гибкость, чем стандартный MD. К тому же,  rST в связке со Sphinx — стандарт документации для open source-проектов.

Разработчики поддерживают документацию в актуальном состоянии, поэтому рассчитывают, что в дальнейшем любое изменение текущей функциональности, как и разработка новой, будет сопровождаться обновлением документации. Это будет одним из Definition of Done для реализации фич.

Помимо документации в релизе 2.1 появилась темная тема и другие обновления интерфейса. Читайте о них в статье →

Pull/Merge Request для согласования требований и документации

Аналитики и технические писатели, признайтесь: сколько раз вы теряли время, сравнивая версии документов в MS Word? Компьютер тормозит, красные и синие правки сливаются в кашу, а поиск согласования в бесконечной переписке или Confluence превращается в квест.

Есть решение — берем механизм Pull/Merge Request и применяем его к текстам! Что получаем:

• Все правки в одном месте. Редактируйте несколько документов сразу и смотрите изменения в едином окне. Забудьте про переключение между файлами и версиями!

• Подробная подсветка. Все правки видны построчно или в удобном визуальном редакторе — сразу ясно, что добавили, убрали или исправили.

• Простое согласование. Назначайте проверяющих и получайте их апрувы прямо в интерфейсе. Никаких "ок" в письмах или мессенджерах!

• Полная история. Все комментарии, согласования и версии сохраняются. В любой момент можно вернуться и проверить, кто, что и когда утвердил.

• Экономия времени. Gramax объединяет редактирование, ревью и согласование в одном месте — больше не нужно жонглировать Word, Confluence и почтой.

И все это в Gramax! Как всегда: бесплатно и с открытым исходным кодом.
Все как в коде, только проще.

💥 Майская версия Gramax 💥

Что нового мы добавили в open source-платформу для управления технической документацией Gramax.

• ИИ-поиск для портала документации. Раньше поиск по документации был ограничен точным совпадением слов, теперь можно подключить ИИ-поиск от любого провайдера (например, OpenAI, Anthropic и др.) и искать по смыслу. Даже при неточном запросе пользователь получит релевантные результаты. Поддерживается как облачное подключение, так и запуск собственного сервера — для тех, кому важна приватность.

• ИИ для создания и редактирования текста. В пространстве редактора можно также подключить ИИ. Он позволит написать текст с нуля: например, если не удается придумать структуру статьи. А также отформатировать существующий текст. В случаях, если его нужно сократить, сделать более формальным или структурированным.

• Шаблоны. Добавили возможность создавать шаблоны со свойствами и использовать их в статьях. 

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

• Расширенный редактор сниппетов. Теперь сниппеты можно оформлять как и обычную статью без ограничений. 

• Выбор формата для исходных файлов. Добавили 2 дополнительных формата хранения статей — XML и GitHub Flavored Markdown. Изменить формат можно в настройках каталога.

• Вход для внешних пользователей в Gramax Enterprise Server. Добавили возможность настроить вход на портал для чтения по почте: таким читателям не нужно иметь учетную запись в SSO. Достаточно указать свою почту при входе и ввести одноразовый код.

О других изменениях читайте в статье — https://gram.ax/resources/docs/whats-new

PlantUML | Шаблон для описания таблиц БД

Делюсь с Вами разработанным мною шаблоном, для описания таблицы БД в PlantUML, c элементами автоматизации, описание которых указанно в комментариях.

Всем привет!
Делюсь с Вами разработанным мною шаблоном, для описания таблицы БД в PlantUML, c элементами автоматизации, описание которых указанно в комментариях.

Протестировать можете тут, а сам код шаблона указан ниже:

 ' Шаблон описания таблицы БД (в PlantUML)
@startuml

skinparam {
' Параметры для управления нижним колонтитулом
    FooterFontColor #blue
    FooterFontSize 12
' Параметры для управления легендой
    LegendBackgroundColor #lightblue
    LegendBorderThickness 0
}

' Переменные для ускорения описания таблицы
' - PRIMARY KEY можно указывать как: "$PK"
    !$PK="  <size:11><#DarkKhaki:key:></size> (PK)  "
' - FOREIGN KEY можно указывать как: "$FK"
    !$FK="  <size:11><#DeepPink:key:></size> (FK)  "
' - NOT NULL (N-N) можно указывать как: "$NN"
    !$NN="  <#LightGreen> **N-N**  "
' - NULL можно указывать как: "$N"
    !$N = "  <#LightCoral> **NULL**  "


' Переменные для ускорения добавления информации о таблице
' - Наименование таблицы БД (латинское)  
    !$table_name="Наимнование_таблицы_БД"
' - Краткое описание таблицы (на русском) 
    !$description="Краткое описание таблицы (на русском)"
' - Ссылка на описание таблицы (на русском)
    !$doc_url="Ссылка"

' Контакты, отображаемые в нижнем колонтитуле
    !$autor ="Зимин Антон"
    !$email ="antzim_in@ya.ru"
    !$telegram="antzim_in"

' Заголовок документа, формируется автоматически из заполненных выше параметров (при необходимости можно удалить)
    title $table_name | $description

' Легенда (может быть заполнена любыми необходимыми данными)
' - "right" говорит о том, что легенда будет расположена справа 
legend right
**Легенда:**
| Версия документа: | 1.0.0 |
end legend



' Описание таблицы
' - заголовок таблицы, с кликабельной ссылкой (если выгружать в SVG) формируется автоматически
class "[[$doc_url $table_name]] ($description)" as $table_name << (T,#FF5722) >>{

|=   PK,FK  |=   Поле   |=   Тип   |=   Обязательность   |=   Значение\n по умолчанию   |=   Описание   |
| $PK | id | serial | $NN | | Идентификатор записи в таблице |
| $FK | subscriber_id | integer | $NN | | Идентификатор записи в таблице subscriber |
|     | electronic_address | varchar(255) | $N | | Электронный адрес \n клиента |
|     | created_at | timestampz | $NN | now() | Дата и время создания записи в БД |
|     | updated_at | timestampz | $NN | now() | Дата и время обновления записи в БД |
}

' Нижний колонтитул (формируется автоматически из введенных параметров)
footer © $autor | tg: [[https://t.me/$telegram @$telegram]] | email: $email
@enduml

Буду рад Вашим комментариям, отзывам, а если еще и поднимите карму то буду крайне благодарен.

Всем спасибо.
----

Пообщаться со мной можно в telegram: @antzim_in
P.S. Также, если Вам интересно, я веду telegram канал @sa_chulan и буду очень рад Вашей подписке.

Тестирование документации: залог успешной разработки

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

Почему важно проверять документацию заранее?

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

Проверка требований до начала разработки помогает находить проблемы раньше, чем они превратятся в баги. Чем раньше найдёшь ошибку, тем меньше потом придётся исправлять. Это называется "Shift-Left Testing", что по сути означает — тестировать раньше, чтобы потом не было больно.

Вот какие проблемы можно найти на этом этапе:

• Противоречия в требованиях: например, в одном месте написано "сохранить данные", а в другом — "удалить данные". Так какой из них правильный?

• Неоднозначные формулировки: когда написано так, что можно понять по-разному, и каждый разработчик это понимает по-своему.

• Отсутствие важных условий: что-то важное просто забыли описать, и программа не знает, что с этим делать.

• Ошибки в сценариях использования: не описаны крайние случаи, например, что делать, если пользователь ввёл неправильные данные.

Как можно тестировать требования?

Есть несколько способов проверить, что в документации нет ошибок:

• Формальная проверка: использование строгих правил, чтобы убедиться, что всё написано правильно.

• Чтение и обсуждение: собираемся, читаем вместе, обсуждаем и находим проблемы.

• Моделирование: создаём простые схемы, чтобы понять, как всё должно работать.

• Анализ текста с помощью ИИ: современные программы могут сами искать ошибки в тексте требований.

Что будет дальше?

Ниже можете видеть видео, где видно, как наш инструмент TestWriter проводит проверку документации с помощью ИИ. Это пока что прототип, но уже видно, как много ошибок можно найти ещё до начала разработки.

Полезные материалы по теме:

• Тестирование требований — Teamlead Roadmap: Простое объяснение, зачем проверять требования перед началом разработки.

• Критерии качества требований с примерами — Habr: Примеры, как сделать документацию понятной и понятной для всех.

• Тестовая документация: что учитывать при постановке эффективного процесса тестирования — Habr: Как правильно описывать требования, чтобы не возникало путаницы.

• Роль формализации требований в тестировании программного обеспечения — КиберЛенинка: Почему важно прописывать требования максимально чётко.

• Тестирование требований — Особенности — Quality Lab: Как работают с требованиями на практике и какие ошибки бывают.

P.S.: а вот ссылка на мой блог в Telegram: https://t.me/it_vadimqa

Шаблон записи о принятии архитектурного решения

# Идентификатор и заговолок

Утверждение о принятом решении.

# Статус

Черновик\Утверждено\Заменено на ADR-XXX

# Контекст

Почему решение необходимо. Предположения, ограничения, мотиваторы принятия решения.

# Критерий оценки

Какие приоритеты в принятии решения? Какие из параметров и характеристик системы рассматриваются или используются в принятии этого решения. Какие мотиваторы и ограничения использовались при принятии решения?

# Доступные варианты

Описывает доступные варианты, изученные при принятии решения согласно критерию оценки(обычно используя рейтинг или оценочную функцию), и компромиссы, возникающие за пределами критерия.

# Решение

Сделанный выбор и аргументация в его пользу.

# Последствия

Положительные и отрицательные последствия принятого решения.

# Консультации

В случае привлечения к обсуждению дополнительных участников, их комментарии документируется здесь. Дополнительная информация о приглашенных, не взирая на наличие от них отклика также записывается тут. Консультации обычно проводятся до принятия решения, но документируются в конце шаблона, чтобы своим объемом и свободной формой не затмевать собственно решение, ради которого создается запись.

Простой, быстрый и бесплатный тест на профориентацию.

1. Кто вызывает у вас зависть? Почему? Что он—она делает? Что именно вас впечатляет в результатах?

2. Что это за роль в экономике: сотрудник в найме, учёный на грантах, волонтёр или вообще целый бизнес?

3. Когда вы почувствовали укол зависти, в каком контексте находился ваш предмет зависти? Выступал на конференции или что-то ещё? Сколько процентов от общего времени занимает эта активность, как думаете?

4. Если выяснится, что для результата, который вызвал у вас зависть, нужно много работать и 80% времени делать рутинные, неинтересные вещи, ваша зависть уменьшится или не сильно?

Если хотите читать вопросы, которые я задаю на менторских сессиях, маякните как-нибудь, буду выкладывать на Хабр дальше.

Инфостиль разрешает вам писать просто и ясно. И не поощряет вас делать вид, что вы умнее, чем вы есть на самом деле.

Всё. Больше инфостиль ни в чём не виноват. Все проблемы, все неудачи — из-за вас, а не из-за инфостиля.

Привет! Сегодня мы хотим представить программу для контрибьюторов Diplodoc — опенсорс-платформы Яндекса для создания документации в формате Docs as Code. Это ваш шанс внести значимый вклад в развитие платформы и получить классные призы за участие.

Мы предлагаем

Мы создали специальную подборку задач, которые вы можете решать, чтобы помочь нам улучшить платформу. Задачи доступны на разных уровнях сложности: easy, medium и hard. Это отличная возможность проявить себя, внести свой вклад в проект и получить заслуженные награды.

Вы получаете

За решение лёгких и средних задач мы подготовили стильный мерч Diplodoc. А за сложные задачи вы вдобавок получите промокод на использование ресурсов Yandex Cloud.

FAQ

Как выбрать задачу?

Вы можете выбрать задачу из нашего списка на странице GitHub и ознакомиться с документацией для контрибьюторов.

Как отправить решение?

Подготовьте PR с вашим решением. Наша команда проверит его. Если в итоге он будет принят, вы получите подарок.

Сколько задачек можно решить?

Сколько угодно, однако приз вы получите только за одно решение.

До какого числа действует программа?

Программа активна до конца января. Мы будем добавлять задачи, так что следите за обновлениями в нашем чате в Telegram!

Не упустите возможность внести свой вклад в будущее Diplodoc!

Используем PlantUML не по назначению: рисуем маппинг данных с помощью диаграммы класса

Когда у вас docs as code, хочется, чтобы все было прямо по «докс экс кодовски», в частности, чтобы диаграммы и схемы тоже рисовались кодом.

Ниже — пример того, как можно изображать маппинг данных с помощью диаграммы классов. Достаточно использовать несколько ухищрений и «костылей», чтобы получать довольно неплохие результаты.

Вот так выглядит код (если нужны пояснения, обращайтесь):

@startuml

hide circle
left to right direction

class Structure_1 {
  field_1
  --
  field_2
  --
  field_3
}

class Structure_2 {
  field_1
  --
  field_2
  --
  field_3
}

package transform <<Rectangle>> #yellow {
  
}

package "addition data" <<Rectangle>> #purple {
  
}

package "data transform" <<Rectangle>> #blue {
  
}

Structure_1::1 -down[#white]-> transform
Structure_1::1 -down-> transform
Structure_1::1 -down[#white]-> transform

transform -down-> Structure_2::1

Structure_1::2 -> Structure_2::2

Structure_1::3 -down-> "data transform"

"data transform" -down-> Structure_2::3

"addition data" -down-> 

А так — результат (маппинг данных):

Какие нюансы нужно учесть:

1. Активно «играйте» связями: они помогают двигать объекты на диаграмме.

2. Используйте невидимые элементы и связи.

Сначала это кажется сложно. Но позже, когда освоишь ухищрения и «костыли», рисовать настоящие шедевры. И тогда у час будет полнейший docs as code.

Похожее можно рисовать и в graphviz, но там синтаксис потяжелее будет. Как? Могу показать.

Стиль — это стиль. Если воспринимать моду на термины и графические знаки именно как моду, предмет перестаёт быть таким уж холиварным. Не нужно спорить. Нужно просто всё время спрашивать себя, на кого я хочу быть похож. На свою жилконтору или на DigitalOcean. Главное не оказаться охранником из книги Пелевина:

— Принято так, — сказал охранник, снимая со стены один из фонарей и протягивая его Сердюку. — Вы ведь галстук тоже не от холода носите.

Вот примеры сложных выборов :)

Вначале было слово e‑mail, потом вариант email (без дефиса) был принят в словари страны происхождения и попал во все англоязычные гайды. То есть был принят большинством. Сейчас дело не в том, нравится вам лично этот вариант или не нравится, а в том, какую одежду вы хотите носить — ту, что была модной десять лет назад, или ту, которую сейчас носит ваша любимая компания.

Ещё пример, тоже про большинство. «Кавычки‑ёлочки». Хорошо сочетаются с кириллическим алфавитом. Носят примерно с 15 века. Но в 21 веке всем внезапно стало лень и теперь я очень часто вижу программистские кавычки в текстах, а не в коде. Мне ёлочки нравятся. Жаль, если их таки вытеснят программистские кавычки. Потому что особого практического смысла это иметь не будет. А красоту мы потеряем.

Была тут относительно "давно" статья от меня.. Прокачивает КД на новый уровень..

Так вот, дозрели тут ещё материалы и предложения от меня.. весьма и весьма интересные..

По этому поводу, собственно опрос..

Прошу, тех кто читал, или ознакомился.. Дать обратную связь в комментариях, или лайках за пост..

Нужна вторая часть безумных предложений? Или нет?

P.s.. прошу либо голосовать за пост, либо в комментариях оставлять "да" либо "нет".. плюс "+" либо минус "-"..

По результатам, чего больше, чего меньше, подведу итог, и приму решение, выкладывать новый материал..

Спасибо..

Этот пост написан специально для одного человека, который спросил, в чате техписателей, как ему, техписателю, «прокачать структуру [технической документации] и силу слова».

Я была бы не я, если бы у меня не нашлось короткого и универсального совета, который подойдет любому человеку, пишущему любой текст, похожий на инструкцию. Ведь техническая документация — суть инструкция.

Универсальный совет

В процессе работы над любым текстом, похожим на инструкцию, регулярно спрашивайте себя:

1. Какую задачу сейчас решает читатель?

2. Какая информация у читателя уже есть?

3. Какой информации читателю не хватает, чтобы решить задачу?

Этот набор вопросов для самопроверки поможет написать техническую статью, выбрать структуру документации, и даже сформулировать вопрос к чату.

Notion уходит из РФ, удаляя все мои данные 9 сентября.

На протяжении многих лет весь IT мир двигался в сторону облачного подхода, в котором я не должен париться об инфраструктуре и просто плачу подписку и дальше хранение данных уже выполняется не мной, а я просто занимаюсь своей жизнью/бизнесом. И вроде как договариваемся, что я могу спать спокойно и не ждать подставы в виде удаления моих данных.

Но последние пару лет явно показали несостоятельность этой модели лично для меня и моего бизнеса. Я все больше и больше возвращаюсь к модели self-hosted решений, которые могут отставать от крутых продуктов, но адаптировать процессы компании проще, чем унижаться и хавать такое нечеловеческое отношение ко мне.

Notion сказал, что 9 сентября просто удалит под чистую все данные без возможности восстановления. Невероятно удобно и надежно и вызывает огромное доверие! Как у них на баннере написано "Write. Plan. Organize." и забыли добавить "... and we'll destroy it".

Прекрасный западный мир, который приглашал к себе меня и мои деньги теперь дает понять, что у этого приглашения есть национальность. А как только я стал неугодный для них, то удаляют меня вместе с моими данными.

Теперь это все время стоит иметь в виду и не воспринимать "Облачный сервис" как что-то надежно. Удобное — да, а вот надежное оно лишь пока я для него буду оставаться удобным в ответ.

Уже лет 10 про роль техписателей активно рассказывают сами техписатели. Однако за последнюю пару месяцев я лично несколько раз слышала вариации на тему: «у нас ТЗ пишут аналитики, значит и на пользовательскую доку аналитика наймём» или «ищем техписателя, который будет писать нам ТЗ». Но добило меня: «я думал, что аналитик — это следующая стадия развития техписателя».

Технический писатель — это тот, кто пишет техническую документацию?

И да и нет. Техническая документация — это не только техническое задание или руководство пользователя. Ошибка — думать, что техническую документацию пишет какой‑то один специалист. Документация нужна на разных этапах разработки продукта, значит и пишут её разные специалисты.

Технический писатель — это тот, кто пишет технические задания?

Нет. Технический писатель создает инструкции к сложным объектам.

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

Я в чём‑то сложном разобралась, научилась этой штукой пользоваться, и объяснила другому так, чтобы он сказал — спасибо, я всё понял. Если штуки ещё не существует, но мне уже надо написать, как с ней работать, то я не техписатель, а, например, менеджер продукта;)

Так, а что техписатель делает на работе?

На работе техписатель разбирается в предметной области, а затем искусно формулирует инструкции для пользователей.