двойная аутентификация, получается

Все правильно 😉 на самом деле, спасибо, я исправлю сейчас!)
А про тег не знала, сейчас добавлю

Спасибо!

видимо не требуется опыт работы именно менеджером знаний.

А такое часто в вакансиях встречается

ну может быть, но все равно читается как-то странно

Все верно, мы же понимаем, что должность в нашей стране пока молодая, поэтому решили, что это может быть инересно техническим писателям.

ну тут же тоже относительно - кому ясна? если это супер очевидно, то может и не нужно писать

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

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

Стоит отметить, что иногда в доке не пишут наоборот какие-то слложные и потенциально опасные вещи, специально чтобы юзеры без саппорта своими ручонками не лезли куда не надо, но это совсем другая история же…

можно поступить как Twilio в своей документации - https://www.twilio.com/docs/voice/twiml/gather#gather-attributes - в таблице дать краткую информацию, которая может быть достаточна для опытных разработчиков, а те, кому нужно больше, могут воспользоваться ссылками на подробные описания каждого из атрибутов.

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

Вот это вообще идеальный вариант! 👍

Я просто адепт подхода - все пихать внутрь, а сверху самое простое

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

на мой взгляд, у Twilio есть проблема с навигацией (без пол-литра не разберёшься сразу, где что искать и что к чему относится), но в самой документации есть чему поучиться и что перенять.

ширина вертикальной полосы прокрутки контента ещё как будто троллирует тебя своей толщиной)

благодарю за развернутый ответ)

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

тут к примеру это параметр steps (оранжевый) в котором лежит несколько степов(этапов) и у каждого свои данные

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

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

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

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

можно ж писать параметры типа
?{{name}}={{value}}
а бывает сразу ?{{value}}
а бывает что тот value еще и как-то шифровать нужно (url encode)
и как-то неудобно в итоге догадываться что ли и пытаться расшифровать, что перед тобой лежит и с какого вопроса начать