Всем привет!
Меня зовут Оксана, подбираю сотрудников в команду Яндекс Облако -  https://cloud.yandex.ru/
Ищу к нам в команду технического писателя - https://yandex.ru/jobs/vacancies/технический-писатель-в-yandex-cloud-6764
Если вам интересна позиция и вы готовы ее обсудить, пожалуйста, пришлите Ваше резюме и примеры работ на почту - appaevaoxana@yandex-team.ru

#wanted_tw

Вот есть форум, раздел военпредов https://nachfin.info/SMF/index.php?action=forum#c13
Можно там пораспрашивать-почитать

🙏Спасибо

Хорошая статья про то как не надо (а как надо) объяснять
https://jvns.ca/blog/confusing-explanations/

Начфин - самое название какое забористое :)

вполне легитимный термин. я на военной кафедре в свое время на начфина и учился )

Рождает яркие образы :) Скрип кирзы, начищенные бляхи - и вот это вот все

от меня и до забора

“avoid introducing unnecessary jargon”

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

Замечание про цикл for и функцию malloc() вообще, увы, характерно для большой части научных книг, особенно это касается учебников. Да простят меня ученики Владимира Зорича.

К вопросу о том, чего стоит избегать при написании документации. Есть такой распространённый  поведенческий паттерн. Разработчики придумывают какую-нибудь сложную концепцию (в сфере разработки коммерческого софта это происходит постоянно), а технический писатель считает своим долгом "задокументировать всё" и начинает в документации рассказывать об этой сложной концепции или замудренной системе. Как я это называю - пытаться натянуть сову на глобус :) А что, на самом деле, должен сделать технический писатель - проанализировать потребности пользователей, и то, как тот или иной функционал помогает пользователю достигать его или ее бизнес-цели, и рассказать ровно об этом. Нет цели - задокументировать всё. Какие-то детали того, что происходит под капотом, лучше не раскрывать, если мы не пишем документацию для разработчиков. И говорить с пользователем нужно на понятном ему языке. Не терминами, которые придумали разработчики, и которые они хотели бы навязать пользователю.

а если пользователи - это разработчики, админы, девопсы, которые работают с системой и пишут под систему?

Ещё одно полезное упражнение, которое я хотел бы предложить всем начинающим техническим  писателям. Допустим, у вас есть задача - рассказать про некий продукт, программно-аппаратный комплекс, или что ещё подобное, что производит ваш работодатель. Вы уже проанализировали потребности целевой аудитории, составили user personas (подробнее об этом читаем - Alan Cooper's Goal-directed design), набросали черновик структуры документа (outline), и даже написали несколько разделов. Теперь нужно перечитать заголовки разделов и ответить себе на вопрос - то, о чем написано - совпадает ли с бизнес-целями пользователя? Проще говоря, когда я вижу в нашей документации какой-то абстрактный заголовок вида Configuring global settings - я сразу подмечаю, что этот текст был написан малоопытным писателем, который увидел в интерфейсе раздел Global settings, и решил задокументировать его. И тут сразу вопрос для самопроверки - а есть ли у нашего пользователя такая задача - configure global settings? Нет, конечно, нет такой задачи. Нужно всё переписать.

А как переписать на примере тех глобал сетингс?

Любые настройки нужно подавать в контексте пользовательской задачи.

То есть условно лучше сделать заголовок вида How to setup $settingsName

Не совсем так. Скорее всего, в переменную SettingsName и в эту часть пользовательского интерфейса разработчики уже запихнули кучу разных настроек, которые они не знали куда ещё запихать :) Нам нужно абстрагироваться от настроек и сфокусироваться на том, что нужно пользователям.

Но при таком подходе может получиться, что для написания документации на условный файрвол уровня Cisco Firepower потребуется квалификация по знаниям соответствующая CCNP (professional). И тогда мы можем опять вернуться к вопросу: зачем работать тех.писателем, если уровень знаний позволяет зарабатывать инженером... Коллизия.

Тоже замечал такое.

Первый подход --- когда просто описываешь интерфейс --- я называю descriptional.

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

Второй подход --- когда отталкиваешься от задач пользователя --- я называю action-based.

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

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