Но вы же это делаете тоже по какой-то причине, а не из простой вредности или консерватизма?)

Наоборот. Не из вредности, а потому что считаю effort и риски

Или если effort получится больше, чем профит от нововведения

Как в анекдоте - "потратить пять часов на автоматизацию одноразовой операции"

Вот! Это правильно и адекватно.

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

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

В общем @Stanislav_techwriter ты сходил бы всё-таки к руководителю, рассказал, как doc-as-code поможет компании справится с бардаком в документации, адом правок в документах, контролем версий и контролем изменений. Как хранение всего в git снизит риски потерять данные. Как переиспользование кусков текста поможет быстрее создавать документы по похожим проектам и снизить количество опечаток. Как каждое заинтересованное лицо всегда сможет получить актуальную, самую последнюю версию документа одним кликом, без необходимости строчить очередное письмо. Попробуй обосновать, как процессы, появившиеся вокруг подхода помогут руководству снизить количество геморроя.

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

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

Кто-нибудь в команде сопротивлялся на тему обязательности? Не всегда же реально есть что написать, а от линтера отбиваться нужно.

Если про методы апи нечего написать, то это странно.

В контексте доки пo REST API в рамках проекта про маркетплейс с понятным ТЗ, одна строчка
"GET /categories"

Даст уже очень много.
Остальную информацию дадут упоминания входных параметров и структуры.

Да, бывает неочевидное поведение отдельных методов, но в моём идеальном мире это решается исправлением поведения.

В лучшем случае, в коммент попадёт, например, "Важно! Авторизационный токен истечёт через Х минут", но это же далеко не у всех методов будет (а если будет, это стоит вынести перед докой).

А что вы туда пишете, что даже правило линтера решили настроить?

Чтобы предлагаемые изменения (улучшение технологии, процесса) получило ход, нужно чтобы были заинтересованные стороны в этом изменении. Для этого надо, чтобы у кого-то где-то болело.
Если твои ПМы не испытывают боли по части документации, то да, нафиг твои усилия никому не нужны. Ты сможешь их заинтересовать только если вытащишь наружу их боли.

Но если ты работаешь по 12-14 часов постоянно, и после этого ещё пытаешься мучать Антору, то, чувак, у меня для тебя плохие новости. Ты скоро сдохнешь и выгоришь при таком графике.
Если у вас все так работают - то понятно, почему никто не хочет слушать об улучшениях - не до этого, нужно тушить пожары. Если это временная ситуация, то нужно переждать и когда всё устаканится, попробовать предложить изменение снова. Если ситуация с переработками - системная, то беги.

Это обычно значит, что процессы плохие

Либо не соблюдаются

Привет, у меня два вопроса:
1. Чем вы редактируете rST? Мне бы какой-нибудь редактор, чтобы там хорошее превью было, всё красиво и понятно. У меня PyCharm под виндой прописную И не пишет, картинок тоже нет. Погуглил, советуют ReText и Formiko, которые только под линукс.
2. Кто подскажет нюансы конвертирования docx в rst с помощью pandoc и главное фильтров pandoc. Я тут всю свою документацию (70 файлов) привел к одному шаблону, с одними стилями и так далее и теперь по идеи при конвертации можно легко задать как какой стиль конвертировать в rst, но я не знаю как, а то щас у меня pandoc даже картинки из ворда не сохраняет никуда, не говоря уже о том, чтобы настроить конвертацию заголовков там или таблиц. Я там тож погуглил, фильтры можно на питоне с помощью panflute сделать, но что-то разобраться с синтаксисом этих самых фильтров не могу, чтобы под свои документы подстроить.

1. PyCharm, но у меня мак и убунта. Картинок нет в превью или где? Наверняка в VSCode нормальный плагин есть.

2. Картинки вот так вытаскиваются: https://t.me/docops/361

А фильтры, говорят, на Lua хорошо писать. @factorized может рассказать подробнее.

Да, в превью нет. Когда html собираешь всё на месте. У нас тут часто мелкие детали интерфейса меняются, и бывает что изменения только картинки и затрагивают, то есть важно при редактировании их видеть. Попробую VSCode тогда.