привет)
а как определить грань, насколько "человеческим" языком и подробно должны быть описаны параметры для апи?

в плане
должно быть по типу
login Логин пользователя в указанном мессенджере
tags Теги, которые нужно присвоить пользователю
phone Номер телефона в международном формате, который нужно добавить к контакту
описание успешного ответа -В случае успешного запроса контакт с указанными переменными будет создан и вы получите ID контакта
и тд

я обычно так писала, но зашла новая инфа и теперь по типу:
login логин
tags Массив тегов
phone Номер телефона
описание успешного ответа - Успешно добавлено

а то что я писала то для маркетологов, а не программистов 🙄
поэтому и параметры ответа вообще расписывать не нужно, а параметры запроса типа так

В последнем абзаце т ответ на вопрос

Евгения, привет. Добавьте, пожалуйста, тэг #wanted_tw в это сообщение.

У нас в компании человеческим языком расписываются параметры. Дока для разработчиков.

ну мне такая позиция не сильно ясна) пока сидела в поддержке и отвечала на такое количество вопросов по этим апи методов,
где в описании и пользователь не разобрался и мне было не особо понятно (если я ещё и сама осталась),
то мне показалось что это нужно указывать все (и ограничения и что делает параметр, указывать его или нет)

Но пользователи разного уровня бывают 🤷🏼‍♀️ кому-то понятно, кому-то нужно детальнее
А кто-то и сам первый раз решил интеграцию сделать, не знает что апи вообще такое и что с этим делать 😁

я про то, что смотря для кого дока. Если для юзеров разного уровня  прошаренности - сделать несколько док/несколько описаний

Мир всем! ✋
Меня зовут Стас, я копирайтер, хочу стать техническим писателем.
Пришёл сюда учиться уму-разуму 👍
Надеюсь, мы подружимся!) =

Стас, привет. Добро пожаловать! Можно и не только учиться, но и чему-нибудь и нас научить!

digitalocean how-to

Пользователи действительно бывают разного уровня, но у юзера, который сходу понимает, есть выбор не читать подробности, ему достаточно будет пробежать по списку параметров, он найдёт нужный по названию и будет счастлив. А вот если другому юзеру (или даже этому самому) нужны будут подробности, которыми вы решили “не засорять” доку, то выбора у него уже не будет и ему придётся идти в саппорт ->  документация свою функцию не выполняет. Так что не писать подробности нужно только если вы точно знаете, что они никому из юзеров не нужны. Что очевидно не является вашей ситуацией, раз вы сами в саппорте имеете такой опыт.

Ну давайте :) если что, готов делиться экспертизой

Поддерживаю. Лучше сразу написать подробно и отсечь кучу вопросов. Если не нужны подробности, можно не читать

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

пока кодить не умею, пишу такие штуки https://habr.com/ru/company/itsoft/blog/548486/

#wanted_tw
Всем привет, хочу поделиться с вами информацией о нашей вакансии Ведущий Менеджер знаний / Lead Knowledge manager, которая открыта в нашей компании.
Чтобы не грузить вас большим текстом, прикрепляю ссылки на информацию о компании и вакансии ниже))
Буду рада ответить на все, интересующие вас вопросы!!!

Кто мы такие: https://midhub.io/

В поиске кого мы находимся:

https://spb.hh.ru/vacancy/46230638

ИМХО в первом варианте есть полезная информация даже для программистов. Хотя бы даже формат, в котором надо телефон отправлять. Лучше описать чуть более подробно, чем надо читателю. Как говорится, лучше перебдеть...

всем спасибо за обратную связь)
а если информация вроде бы как и так ясна?

ну по типу
создается контакт
в параметрах указывается там телефон, тег, переменная и тд
пишем ли мы
список тегов, которые нужно присвоить пользователю
мессенджер, по которому можно связаться с пользователем в чате. Может принимать значения x, x, x.
ну вроде как и так понятно что все что добавляешь - присвоится пользователю
и вроде понятно что мессенджер для связи и только через чат)

вот эта еще грань
дать все нужное
но не перестараться разжевать и нагрузить)

тег #wanted_tw добавьте в сообщение, тут так принято
и чё за прикол в вакансии: Требуемый опыт работы: не требуется
ниже: не менее 3 лет опыта в роли технического писателя

тест на внимательность, видимо

тест на внимательность ещё ниже отдельно