Используйте стайлгайд от микрософт

Можете посмотреть у Google style guide.
Это называется formatting of user interface elements.

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

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

Отдельно держим нормальную текстовую документацию, отдельно сваггер, на который ссылки даем в большой доке

Точно, ещё и без “on”
Google style guide ещё не смотрела, спасибо!

Всем спасибо за ответы :)

Ого, а есть пример такой документации?

Думала если свагер, так уже только он

Я вот так разделяла:


https://developer.servicechannel.com/

почему оповещения не могут приходить машинам?

Субъективное ощущение. А ещё оповещение это notification. Чтобы не было коллизии терминов, хорошо бы webhook перевести иначе.

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

что нужна львиная доля терпения с попыткой задушит в себе - "все хватит, сами пишите!"

Как-то с другими субъектами компании было проще общаться, через тим лида или проект менеджера - задачи доволи понятно расписывали.
а тут впервый раз сырое кинули где почти ничего нет и не описано и без объяснений и без проект менеджера или какого либо еще "посредника"

если понимать все на уровне программиста - чего бы работать райтером?) можно самому программить и получать больше)

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

Терпение, терпение, терпение. У меня тоже такие ребята есть) иногда проще по аналогиям объяснять, что именно нужно + хорошо работает предложить, как понимаешь работу того или иного и провалидейтить у них, типа так или не так

Только смириться и терпеть😂

Я встречала программистов, которые на полном серьезе говорили: ты что глупая, как это можно не понять? И приходилось призывать переговорщиков в лице менеджера/тимлида

ну пока это так и получается
то "вообще, для реальных пользователей API, swagger не должен вызывать вопросов
он и придуман для того, что не было вопросов и статьей по 100500 строк описывающих каждую строчку"

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

ну и различные моменты типа я скромно - а тут неплохо бы добавить пример с файлом

а на меня тааак накинулись
прям кепс лок

"ЭТО ФАЙЛ
он не вставляется в JSON
любой программист, спосбодный отправить такое понимает что это"

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

Нужно всегда призывать третью сторону в таком случае, мне кажется

Программистам все всегда понятно. Ровно до того момента, пока они не сталкиваются с кодом, который в глаза не видели

Как сказал великий

Техпису от природы надлежит плакать.
Такова его ТП-участь.