Миф о документации, продолжение

[gaperton]

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

Давайте посмотрим, почему же люди пишут документы тогда, когда они их действительно пишут, а не рассуждают о том, как бы хорошо было, если бы они были, и как плохо,

Comments

[_winnie]

> > Во-первых постулируется что писать буду потому не умеют объяснять.
> Нет такого утверждения в моем тексте.
Альтернатива в тексте не рассматривается, только красочно расписана как неправильно когда пишут те, кто не умеют объяснять.

> > Это может быть не так, часто пишут именно что бы не объяснять 1000 раз ("какие параметры у скрипта и где его файлы.")
> Это справочная информация, а не учебная.
Тогда сложность создания и поддержки справочной информации переусложнена (в пример приводятся ISO), а нужность недооценена, и непонятно что такое вообще учебная информация.

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

Кстати, ещё непонятно как исправить баг, который не воспроизводится (напр. racing condition который тестеры пока что не воспроизведли). Если же тестеры для этого не нужны, то можно создать кнопку "сделать коммит и сделать на это таск в Jira". Только это приведёт к тому, что в Jira будет миллионы "багов" про "исправил опечатку" и будет тратится время на её оптимизацию.

[gaperton]

>>> Во-первых постулируется что писать буду потому не умеют объяснять.

>> Нет такого утверждения в моем тексте.

> Альтернатива в тексте не рассматривается, только красочно расписана как неправильно когда пишут те, кто не умеют объяснять.

Опять таки, нет ничего подобного в моем тексте.

Люди, не умеющие (и не желающие) читать, что написано, лишаются права комментировать в моем журнале.

http://linorg.ru/how-to-read.html

Ибо объяснять им что-либо бесполезно. Всего доброго.