документация

[amarao]

Кажется, я начинаю понимать как писать документацию.

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

Озарение началось с вопроса от техписа "а где ваши шаблоны? (для документации)".

Comments

[juan_gandhi]

Хмм. А в голове шаблоны - это плохо?

[amarao]

Не знаю. Зависит от того, что за шаблоны.

Для документации шаблоны в голове - не работает. Человек, который пишет, хочет писать о том, что ему хочется написать. А хорошая документация пишется о том, о чём другие хотят прочитать, и это не одно и тоже.

Более того, она пишется не только о чём другие хотят прочитать, но и пишется одинаково каждый раз, так что каждый читающий знает, что от неё ожидать.

Повторяемость, про то, что хотят читать, с общим словарём - считай уже окей документация. Если куски кода из документации (команды и т.д.) проверяются CI'ем, вообще прекрасно.

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

[provokatorz]

AI подрядить не выход?

[amarao]

Если мне нужен slop, конечно, сработает. Если рабочая документация - откуда AI это знает?

Хотя заставить AI пройтись по чек-листу для документации - может быть, неплохая идея. Зависит от числа false positive.