У каждого, думаю, наберётся стопка вкладок с интересными статьями или вебинарами - хорошего контента много и естественно не успеваешь все переваривать.
В последнее время взял себя в руки и периодически просматриваю интересующие вещи (думаю будет несколько полезных конспектов🙃). Одним из таких источников является Moscow Python Podcast - выпуск Docs as Code - документация как код. Вообще я сторонник всего структурированного и что можно версионировать (привет git), поэтому тема была интересна.
Прозвучало несколько подходов:
- без документации 🤷‍♂️
- дока в Jira/Notion/Confluence...
- дока рядом с кодом

Соображений было много, но кажется ребята сошлись на одной мысли - лучше отсутствие доки, чем её неконсистентная версия, тк создаёт накладные ментальные расходы.
Наличие Docs as Code, а особенно когда интегрировано с CI/CD - также создаёт накладные расходы, мало пофиксить код, система требует пофиксить доку, но если ты не знаешь где, что и как (привет 234 markdown файла), то оказываешься в ступоре.

Вот вам тезисы:
1️⃣ Писать доку - хорошее правило
2️⃣ Пишешь доку - поддерживай
3️⃣ Если не поддерживаешь - лучше не пиши🤷‍♂️
4️⃣ На каком языке - английский vs русский - выбор скорее зависит от команды\продукта (если есть мждународный рынок лучше английский)
5️⃣ Без доки вход новых сотрудников усложняется


Гость программы рассказал про оригинальную методологию разработки - Literate Programming .
Написание программного кода как прозы - не знаю насколько идея работоспособна, но заслуживает внимание своей оригинальностью 😉

Вывод можно извлечь такой:
📍Принимать решение о документации надо в начале (сколько, где и как)
📍И можете оставлять нецензуршину - так веселее😉