Илья, а можно я твоё сообщение чуть отформатирую и в канал запощу?

Я всё же сторонник попробовать сразу сделать нормально, чем потом искать ошибки после.

да, конечно

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

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

всем привет! Я сейчас разрабатываю API документацию (пока бумажную, потом будем переводить на сваггер). И такой вопрос. Как вы думаете, куда добавить описание кодов ошибок: после описания каждого endpoint-а или же в виде отдельного приложения в конец документа?

После каждого, пусть даже отсылкой к общему

И у тебя обязаны быть (в силу флуктуаций пррстранства-времени) кастомные ошибки в отдельных методах. Поэтому в каждом.

Мне кажется и после каждого и вконце справочно  все ошибки

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

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

Вспомнил ещё в тему повышения ЗП. Если бизнес видит от сотрудника толковые инициативы, и если они ещё реализуются, то такому сотруднику вполне могут дать повышение с целью мотивировать работу, дать больше ресурсов и полномочий для реализации. Опять сужу по своему же опыту, на текущей и предыдущей работе продвигался как раз за счёт анализа бизнес-процессов и предложений их оптимизации. Правда, нужно помнить о внутренних правилах повышения + уметь ждать. Например, на текущей работе я не могу сейчас стать куратором по направлению документации, так как не проработал достаточно времени (устроился 10 месяцев назад), но в начале будущего года я могу им стать, руководство это приветствует и обсуждалось это буквально на прошлой неделе.
Краткий итог: если у техписа возникают вопросы о его ЗП, он сразу же должен задать себе встречный вопрос о том, как конкретно его деятельность приносит деньги бизнесу, и как бизнес может увеличить свой текущий бюджет за счёт услуг техписа. Мыслите как менеджер/бизнесмен, и тогда будет рост.

я бы не стал добавлять в конце, потому что 1) вам будет тяжело обновлять их сразу в двух местах, в результате версии разойдутся; 2) сомневаюсь, что кто-то будет искать их в конце.

И я согласен с Игорем, появятся кастомные ошибки. И вам придётся писать, что вот там 404 означает то, а вот тут — это. Читатель запутается.

А почему вы начинаете с бумажной? Чем это легче?

Ну и наконец, смысла не вижу в общем списке кодов ошибок. Они же не имеют точного смысла в отрыве от конкретного метода. Как список переменных или классов в коде сделать.

на самом деле, у нас есть прототип на свагере, но:
1). там нет описания бизнесовой части
2). далеко не все endpoint-ы нужно передавать тем, кто будет с нами интегрироваться
3). документацию надо передать интеграторам в течение нескольких дней, а разбираться со свагером, думаю, займет по времени куда больше

Приветствую вновь прибывших )

Привет! Вижу, у вас тут любят документацию так же сильно, как и я :)

Ага. Этот чатик я завёл как дополнение к каналу. Есть ещё большой чат, когда-то основанный питерским сообществом техписателей.

Я сюда из DocOps / Docs as code попал.